From 554b04d66a6e24390945bb5747b1ed3a3d5cb741 Mon Sep 17 00:00:00 2001 From: bidi47 Date: Thu, 1 Oct 2026 14:46:46 +0300 Subject: [PATCH] regenerated page - upgrade api v6 to v7 Signed-off-by: bidi47 --- .claude/skills/upgrade-plan/SKILL.md | 6 ++-- .claude/skills/upgrade-plan/gather.sh | 29 ++++++++++++++--- docs/book/v7/upgrading/UPGRADE-7.0.md | 46 +++++++++++++++++++++------ 3 files changed, 66 insertions(+), 15 deletions(-) diff --git a/.claude/skills/upgrade-plan/SKILL.md b/.claude/skills/upgrade-plan/SKILL.md index faf6d5b..295cc5b 100644 --- a/.claude/skills/upgrade-plan/SKILL.md +++ b/.claude/skills/upgrade-plan/SKILL.md @@ -33,7 +33,9 @@ Do not create the page, edit `mkdocs.yml` or edit any other file until the user - titles that disagree with the code, such as a class named differently in the title and the diff - release-note oddities: a changelog entry missing most pull requests, or dated differently from the release - which branch the release comes from, since a minor release may come from the previous branch -5. **Scope.** List commits on the release branch after the tag as out of scope and unreleased. +5. **Scope.** Read the last section of the gather output. + If it says the release was superseded, state that later commits belong to the named newer release and point to its plan; list no unreleased commits. + Otherwise list the commits on the release branch after the tag as out of scope and unreleased. 6. **Write the plan** to `.claude/PLAN-UPGRADE-.md`, using the layout below. 7. **Lint and report.** Run `npx --yes markdownlint-cli2 --config ~/.claude/markdownlint.jsonc ".claude/PLAN-UPGRADE-.md"` and fix every issue. @@ -71,7 +73,7 @@ Follow `.claude/PLAN-UPGRADE-7.1.md` if it exists, otherwise this order: 3. Findings that shape the page: the headline changes and the step 4 cross-checks. 4. Pull requests: an important table and an optional table with `PR | Description`, each PR as a full URL, most impactful first. Escape `|` inside table cells as `\|`. -5. Out of scope: unreleased commits. +5. Out of scope: unreleased commits, or a note that the release was superseded and by which one. 6. Page outline: the newest existing `UPGRADE-*.md` is the template, with the same headings, one sentence per line and the same bullet marker. Details has `### Important updates` and `### Optional updates`, and the FAQ covers PHP versions, migrations, moved config, and whether optional updates are required. 7. Files to change on execution: the new page, the nav entry in `mkdocs.yml` (newest first), and `upgrading.md` only if it links the other version pages. diff --git a/.claude/skills/upgrade-plan/gather.sh b/.claude/skills/upgrade-plan/gather.sh index ac04cb8..98e8519 100755 --- a/.claude/skills/upgrade-plan/gather.sh +++ b/.claude/skills/upgrade-plan/gather.sh @@ -38,7 +38,28 @@ while read -r pr; do -q '"### #\(.number) \(.title)\n- merged: \(.mergedAt)\n- files: \([.files[].path] | join(", "))\n"' done -echo "## Commits on branch $BRANCH after tag $TO (unreleased)" -gh api "repos/$REPO/compare/$TO...$BRANCH" \ - --jq '"- ahead: \(.ahead_by)", (.commits[] | "- \(.sha[0:7]) \(.commit.message | split("\n")[0])")' 2>/dev/null || - echo "- (branch $BRANCH not comparable)" +# Earliest non-draft, non-prerelease release on the same branch published after $TO. +# `gh release list` does not expose the target branch, so look it up per candidate. +TO_PUBLISHED="$(gh release view "$TO" -R "$REPO" --json publishedAt -q .publishedAt)" +NEXT="" +while read -r candidate; do + [ -n "$candidate" ] || continue + candidate_branch="$(gh release view "$candidate" -R "$REPO" --json targetCommitish -q .targetCommitish)" + if [ "$candidate_branch" = "$BRANCH" ]; then + NEXT="$candidate" + break + fi +done < <(gh release list -R "$REPO" --limit 100 --json tagName,publishedAt,isDraft,isPrerelease \ + -q "[.[] | select(.isDraft == false and .isPrerelease == false and .publishedAt > \"$TO_PUBLISHED\")] | sort_by(.publishedAt) | .[].tagName") + +if [ -n "$NEXT" ]; then + echo "## Commits after tag $TO" + echo "- superseded by release $NEXT on branch $BRANCH: later commits belong to $NEXT or newer, so none are listed as unreleased" + NEXT_COUNT="$(gh api "repos/$REPO/compare/$TO...$NEXT" --jq .ahead_by 2>/dev/null || echo "?")" + echo "- commits between $TO and $NEXT: $NEXT_COUNT" +else + echo "## Commits on branch $BRANCH after tag $TO (unreleased)" + gh api "repos/$REPO/compare/$TO...$BRANCH" \ + --jq '"- ahead: \(.ahead_by)", (.commits[] | "- \(.sha[0:7]) \(.commit.message | split("\n")[0])")' 2>/dev/null || + echo "- (branch $BRANCH not comparable)" +fi diff --git a/docs/book/v7/upgrading/UPGRADE-7.0.md b/docs/book/v7/upgrading/UPGRADE-7.0.md index e438f6e..d7bbe6e 100644 --- a/docs/book/v7/upgrading/UPGRADE-7.0.md +++ b/docs/book/v7/upgrading/UPGRADE-7.0.md @@ -3,17 +3,28 @@ ## Summary The changes you need to port into your project when moving from Dotkernel API 6.x to 7.0, each linked to the pull request that introduced it. -The headline items are native UUIDs in the database, PostgreSQL support, and the removal of the `MethodDeprecation` implementation. +The headline items are native UUIDs in the database, PostgreSQL support with renamed database connection keys, and the removal of the `MethodDeprecation` implementation. +Version 7.0 does not change the PHP version or any Composer dependency constraint. ## Details -> You can find a complete list in [Changelog](https://github.com/dotkernel/api/blob/7.0/CHANGELOG.md) +> You can find the release notes in [7.0.0](https://github.com/dotkernel/api/releases/tag/7.0.0) and a complete list in [Changelog](https://github.com/dotkernel/api/blob/7.0/CHANGELOG.md) + +### Important updates + +These changes affect your database schema, configuration, entities or runtime behavior. + +* Use native UUIDs in database via `ramsey/uuid`: entities get their identifier from the new `UuidIdentifierTrait` and a `UuidType` that declares the SQL type `UUID`. `getUuid()` becomes `getId()` and the `uuid` key becomes `id` in entities, repositories, services, input filters and OpenAPI. A schema migration is required [https://github.com/dotkernel/api/pull/456](https://github.com/dotkernel/api/pull/456) +* PostgreSQL implementation: in `config/autoload/local.php.dist` the `default` connection is renamed `mariadb`, a `postgresql` connection is added, and `charset` and `collate` are replaced by `collation`. `AbstractEnumType` is reworked, `MigrationsMigratedSubscriber` is added and `config/cli-config.php` is updated [https://github.com/dotkernel/api/pull/462](https://github.com/dotkernel/api/pull/462) +* Remove `MethodDeprecation` implementation: the attribute and its tests are deleted, and `DeprecationMiddleware` and the error-report handler no longer use it [https://github.com/dotkernel/api/pull/470](https://github.com/dotkernel/api/pull/470) + +### Optional updates + +These changes cover documentation and comments. +Skipping them does not affect how the API runs. -* Use native UUIDs in database via `ramsey/uuid` [https://github.com/dotkernel/api/pull/456](https://github.com/dotkernel/api/pull/456) -* updated readme, oss [https://github.com/dotkernel/api/pull/461](https://github.com/dotkernel/api/pull/461) -* PostgreSQL implementation [https://github.com/dotkernel/api/pull/462](https://github.com/dotkernel/api/pull/462) -* Remove `MethodDeprecation` implementation [https://github.com/dotkernel/api/pull/470](https://github.com/dotkernel/api/pull/470) * Clarify instructions regarding multiple connections in `config/autoload/local.php.dist` [https://github.com/dotkernel/api/pull/472](https://github.com/dotkernel/api/pull/472) +* Update readme and security documents [https://github.com/dotkernel/api/pull/461](https://github.com/dotkernel/api/pull/461) ## FAQ @@ -23,20 +34,37 @@ A: No. You implement each listed change manually in your own project. See [Upgrades](upgrading.md) for the recommended procedure. +**Q: Do I need to change my PHP version or dependencies?** + +A: No. +The PHP constraint and the Composer dependencies are the same in 6.1.0 and 7.0.0. + +**Q: Which code or configuration do I need to rename?** + +A: Rename `getUuid()` to `getId()` and the `uuid` key to `id` wherever your own code uses them. +In your `config/autoload/local.php`, rename the `default` database connection to `mariadb` and replace `charset` and `collate` with `collation`. +Compare your file with `local.php.dist` from the 7.0 branch. + **Q: What does the switch to native UUIDs mean for my database?** -A: Identifiers are stored using the database's own UUID handling via `ramsey/uuid` rather than a generic column type, so existing tables need a migration. +A: The identifier column type changes from `uuid_binary` to the database's `UUID` type, through a `UuidType` that extends the `ramsey/uuid-doctrine` type. +The release does not ship a migration file, so existing tables need a migration that you write for your own schema. Review pull request 456 before touching production data. **Q: Do I have to move to PostgreSQL in 7.0?** A: No. -PostgreSQL is now supported in addition to MariaDB; either is a valid choice. +PostgreSQL is now supported in addition to MariaDB; either is a valid choice, and MariaDB remains the default connection. **Q: `MethodDeprecation` was removed — how do I deprecate an endpoint now?** A: Use the deprecation approach described in [API evolution](../tutorials/api-evolution.md). +**Q: Do I have to apply the optional updates?** + +A: No. +They only concern documentation and comments. + **Q: Where do I find the complete list of changes?** -A: In the project [CHANGELOG.md](https://github.com/dotkernel/api/blob/7.0/CHANGELOG.md). +A: In the [7.0.0 release notes](https://github.com/dotkernel/api/releases/tag/7.0.0) and the project [CHANGELOG.md](https://github.com/dotkernel/api/blob/7.0/CHANGELOG.md).