Merge pull request #175 from dotkernel/upgrade-7.1

regenerated page - upgrade api v6 to v7

Author: arhimede

.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-<to>.md`, using the layout below.
 7. **Lint and report.**
    Run `npx --yes markdownlint-cli2 --config ~/.claude/markdownlint.jsonc ".claude/PLAN-UPGRADE-<to>.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.

.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

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).