|
| 1 | +--- |
| 2 | +name: upgrade-plan |
| 3 | +description: > |
| 4 | + Use when asked to plan, prepare or draft a new upgrade page for the Dotkernel documentation — for |
| 5 | + example "plan the 7.1 to 7.2 upgrade page", "what changed between releases", or "list the pull |
| 6 | + requests for the next upgrade guide". Produces a plan file in .claude/ that lists the pull |
| 7 | + requests of a release, split into important and optional updates, based on the release notes, |
| 8 | + commits and code of the source repository. Planning only: it does not create the page. |
| 9 | +--- |
| 10 | + |
| 11 | +# Upgrade page plan |
| 12 | + |
| 13 | +Produce `.claude/PLAN-UPGRADE-<to>.md` for a new `docs/book/v<major>/upgrading/UPGRADE-<to>.md` page. |
| 14 | +This skill only plans. |
| 15 | +Do not create the page, edit `mkdocs.yml` or edit any other file until the user approves the plan and asks for it. |
| 16 | + |
| 17 | +## Inputs |
| 18 | + |
| 19 | +- `from` and `to`: the release tags, for example `7.0.0` and `7.1.0`. Ask if either is missing. |
| 20 | +- `repo`: defaults to `dotkernel/api`. Other Dotkernel repositories work the same way. |
| 21 | +- Check the tag exists with `gh release list -R <repo>` before going further. |
| 22 | + |
| 23 | +## Steps |
| 24 | + |
| 25 | +1. **Gather.** Run `bash .claude/skills/upgrade-plan/gather.sh <from> <to> [repo] > <scratchpad>/upgrade-<to>.md` and read the output. |
| 26 | + It prints the release notes, commit and file counts, the `composer.json` diff, the files touched by each pull request, and the commits on the release branch after the tag. |
| 27 | +2. **Read the code.** Never classify from titles. |
| 28 | + For every pull request that touches `src/`, `config/`, `bin/`, `composer.json`, migrations or entities, read its diff with `gh pr diff <n> -R <repo>`. |
| 29 | + With many pull requests, hand this step to a subagent and keep only its conclusions. |
| 30 | +3. **Classify** each pull request as important or optional using the rules below. |
| 31 | +4. **Cross-check** and record the findings in the plan: |
| 32 | + - pull requests that must be read together, for example one removes a file and a later one recreates it elsewhere |
| 33 | + - titles that disagree with the code, such as a class named differently in the title and the diff |
| 34 | + - release-note oddities: a changelog entry missing most pull requests, or dated differently from the release |
| 35 | + - which branch the release comes from, since a minor release may come from the previous branch |
| 36 | +5. **Scope.** List commits on the release branch after the tag as out of scope and unreleased. |
| 37 | +6. **Write the plan** to `.claude/PLAN-UPGRADE-<to>.md`, using the layout below. |
| 38 | +7. **Lint and report.** |
| 39 | + Run `npx --yes markdownlint-cli2 --config ~/.claude/markdownlint.jsonc ".claude/PLAN-UPGRADE-<to>.md"` and fix every issue. |
| 40 | + Tell the user the counts, the headline items, and anything from step 4 that needs a decision. |
| 41 | + |
| 42 | +## Classification rules |
| 43 | + |
| 44 | +Important: the change affects a project that has copied the skeleton. |
| 45 | + |
| 46 | +- PHP version constraint, or any change to `require` or `conflict` in `composer.json` that reaches runtime |
| 47 | +- major version bumps of runtime dependencies |
| 48 | +- configuration files added, removed, renamed or with changed keys |
| 49 | +- database schema: entity columns, enums, DBAL types, migrations |
| 50 | +- entity, repository, service or interface signature changes |
| 51 | +- new or changed middleware, pipeline or routes, and any change of response, header or error behavior |
| 52 | +- security fixes and security headers |
| 53 | +- changes to Composer scripts or the post-install script |
| 54 | + |
| 55 | +Optional: skipping it does not change how the application runs. |
| 56 | + |
| 57 | +- CI workflows and GitHub Action bumps, Renovate, Qodana, code coverage |
| 58 | +- README, changelog and other documentation, API collections |
| 59 | +- dev-only dependencies with no effect on project code, and comment or type-only cleanups |
| 60 | +- config `.dist` clarifications |
| 61 | + |
| 62 | +When unsure, classify as important and say why in the description. |
| 63 | +State the condition where a change only matters sometimes, for example "only when using PostgreSQL". |
| 64 | + |
| 65 | +## Plan layout |
| 66 | + |
| 67 | +Follow `.claude/PLAN-UPGRADE-7.1.md` if it exists, otherwise this order: |
| 68 | + |
| 69 | +1. Goal, including the target file path and the page used as the template. |
| 70 | +2. Sources checked: release dates, target branch, commit and file counts. |
| 71 | +3. Findings that shape the page: the headline changes and the step 4 cross-checks. |
| 72 | +4. Pull requests: an important table and an optional table with `PR | Description`, each PR as a full URL, most impactful first. |
| 73 | + Escape `|` inside table cells as `\|`. |
| 74 | +5. Out of scope: unreleased commits. |
| 75 | +6. Page outline: the newest existing `UPGRADE-*.md` is the template, with the same headings, one sentence per line and the same bullet marker. |
| 76 | + Details has `### Important updates` and `### Optional updates`, and the FAQ covers PHP versions, migrations, moved config, and whether optional updates are required. |
| 77 | +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. |
| 78 | +8. Verification: markdownlint, a check that every PR URL from the release notes appears exactly once, `mkdocs build --strict` if available, and a check of versions against `composer.json` at the tag. |
| 79 | + |
| 80 | +## Rules |
| 81 | + |
| 82 | +- Every claim in the plan and in later FAQ answers must come from a diff or the release notes, not from memory. |
| 83 | +- Link pull requests by full URL, as the existing upgrade pages do. |
| 84 | +- Major releases (for example 6.x to 7.0) need migration guidance in the FAQ and not just a pull request list; say so in the plan. |
| 85 | +- Never publish or share the plan outside the repository. |
0 commit comments