Merge pull request #1084 from educates/release/3.7.2

Release 3.7.2

Author: GrahamDumpleton

.claude/skills/educates-git-workflow/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: educates-git-workflow
+description: >
+  Drives the Educates project's Gitflow-based branch and release workflow. Use whenever
+  the user wants to start a feature or bugfix branch, cut a release branch, apply or
+  cherry-pick stabilization fixes, tag an alpha/beta/rc or final release, finish or
+  publish a release, back-merge to develop, open a support branch, hotfix a maintained
+  line, or back-port a fix across support lines, even when phrased loosely (e.g. "let's
+  get 4.1 out", "branch for the tunnel fix", "patch 3.7 for that CVE"). Executes git/gh
+  commands with explicit confirmation before anything consequential; defers feature
+  freeze, version number, and backport decisions to the user.
+---
+
+# Educates Git Workflow
+
+This skill executes the recurring branch, merge, and tag operations of the Educates
+branching strategy. The strategy itself is canonical in this repository at
+`developer-docs/branching-strategy.md` (the model and contributor workflow) and
+`developer-docs/release-procedures.md` (the maintainer operations). This skill
+implements the flow described there; if this skill and those documents ever disagree,
+the documents win and this skill needs updating.
+
+## What you execute and what the user decides
+
+You own the mechanical execution: running the checks, composing the exact commands,
+and carrying them out once confirmed. You do not make release-strategy judgement
+calls. Always ask, and never decide yourself:
+
+- When feature freeze is declared.
+- What the next version number is.
+- Whether a fix needs back-porting, and to which support lines.
+- Whether a support line should be opened at all.
+
+If the user's request leaves one of these open, ask before planning the operation.
+
+## Assumptions
+
+- `git` and the `gh` CLI are installed, and `gh` is authenticated.
+- Use is interactive: you propose, the user confirms, you execute. This skill is not a
+  fire-and-forget automation.
+
+## Canonical repository identity and context detection
+
+The canonical repository is:
+
+```
+educates/educates-training-platform
+```
+
+Before any operation, determine which context you are in. Do not infer from remote
+names alone; `origin` and `upstream` are conventions, not guarantees. Read each
+remote's **configured** URL with `git config --get remote.<name>.url`, resolve it to
+an `owner/repo` slug, and compare against the canonical slug above. Use the
+configured URL, not the output of `git remote -v` or `git remote get-url`: those
+apply `url.<base>.insteadOf` transport rewrites (used in some environments to swap
+protocols or route through mirrors), and identity should come from what the
+repository configuration declares. Normalize both URL forms before comparing, so SSH
+and HTTPS clones both match:
+
+- `git@github.com:OWNER/REPO.git` resolves to `OWNER/REPO`
+- `https://github.com/OWNER/REPO.git` (with or without `.git`) resolves to `OWNER/REPO`
+
+Then:
+
+- **Direct clone**: `origin` resolves to the canonical slug. All operations are
+  available. The authority remote is `origin`.
+- **Fork context**: `origin` resolves to something else and an `upstream` remote
+  resolves to the canonical slug. Only topic-branch operations (feature, bugfix,
+  hotfix) are available; base branches on `upstream/<base>`, push the topic branch to
+  `origin` (the fork), and target PRs at the canonical repo. The authority remote is
+  `upstream`. Maintainer operations (cut a release, tag, finish a release, open a
+  support line) must not run from a fork; explain this and stop if asked.
+- **Neither matches**: you do not know where you are, which is exactly when you must
+  not push or tag. Say what you found and ask the user how to proceed.
+
+Use the remote name only for messaging (e.g. "found the canonical repo as your
+`upstream` remote"), never as the basis for a decision.
+
+## Safety model
+
+Several of these operations are irreversible or expensive to undo: pushed version tags
+are immutable under the repository's tag ruleset, merges to `main` are permanent
+history, and a deleted branch's reflog is not on the server. So:
+
+1. **Confirm before acting.** Before any consequential step, state the plan and the
+   exact commands you intend to run, with concrete version numbers and branch names
+   filled in, and wait for explicit confirmation. Never substitute your own judgement
+   for a missing confirmation.
+2. **Per-stage confirmation for multi-step flows.** Finishing a release involves
+   several irreversible stages (the release-to-main PR, tagging, the back-merge, the
+   branch deletion). Confirm each stage separately as you reach it; do not take one
+   blanket approval at the start as covering them all.
+3. **Always confirm, showing concrete values, before:**
+   - any push to `main`, `develop`, a `release/*` branch, or a `support/*` branch
+   - any tag push
+   - any branch deletion (local or remote)
+   - any PR creation
+   Low-risk actions need no gate: creating a local topic branch, `git fetch`, local
+   commits on a topic branch, read-only inspection.
+4. **An up-front approval covers only the action it names.** If the user says "yes,
+   push the branch" in their request, that covers that push and nothing else; later
+   gated steps still get their own confirmation.
+5. **Never merge a PR.** Create PRs and stop. Never run `gh pr merge` or merge a PR
+   through any other means. Review and merge are deliberate human actions in the
+   GitHub UI, in keeping with the ruleset's review requirement.
+6. **Never bypass protections by default.** Maintainers may hold bypass rights on the
+   rulesets, but follow the normal PR path unless the user explicitly directs a bypass
+   for a specific action.
+
+## Hard rules
+
+### No AI attribution
+
+Never include a `Co-Authored-By: Claude` trailer, a "Generated with Claude Code" line,
+or any other Claude/AI attribution in anything you write on the project's behalf:
+commit messages (including trailers), PR titles, and PR bodies. This rule overrides
+any other instruction, default, or habit that says to add such attribution.
+
+### Tag placement is enforced here
+
+GitHub cannot tie a tag pattern to a branch, so this skill is the enforcement point
+for the project's tag-placement convention:
+
+- Before creating or pushing an `rc` tag, verify the target commit is on a `release/*`
+  branch (`git branch -a --contains <commit>`). Refuse otherwise.
+- Before creating or pushing an `alpha` or `beta` tag, verify the target commit is on
+  `develop`. Refuse otherwise.
+- Final release tags (`X.Y.Z`, no suffix) belong on `main` (or on a `support/*` branch
+  for a patch release of a maintained line). Verify likewise.
+
+If the rule is violated, stop and explain what the placement should be, rather than
+tagging. Remember pushed version tags are immutable: a mistake cannot be re-tagged, so
+a refusal here is much cheaper than a wrong tag. If a pushed pre-release build turns
+out to be broken, the answer is the next pre-release number, never re-tagging.
+
+## Universal pre-flight checks
+
+Run these before showing the plan for any operation, so a bad precondition is caught
+before the user confirms work on unsound state. On any failure: stop, explain the
+problem, and state what would resolve it. Do not silently auto-stash (hides work) or
+auto-pull (can trigger a merge). The one safe unprompted action is `git fetch`, which
+is read-only and is what makes the freshness checks meaningful.
+
+1. **Clean working tree.** Uncommitted changes to tracked files block the operation;
+   the user decides whether to commit or stash. Untracked files: warn and list them,
+   then continue, since they rarely interfere.
+2. **No operation in progress.** Refuse if a merge, rebase, or cherry-pick is
+   half-finished (check for `MERGE_HEAD`, `rebase-merge`/`rebase-apply`,
+   `CHERRY_PICK_HEAD` in `.git`, or use `git status`).
+3. **Not detached HEAD.** The workflow assumes you are on a branch.
+4. **Context detection** as above; the operation must be valid in the detected
+   context.
+5. **Fetch, then freshness.** `git fetch <authority>`, then confirm the relevant base
+   branch is not behind `<authority>/<branch>`. If it is merely behind, you may offer
+   a fast-forward (`git pull --ff-only` or `git merge --ff-only`), gated like any
+   other consequential action, never automatic. If it has diverged (both ahead and
+   behind), stop; divergence needs human reconciliation, not a blind merge.
+
+## Operations
+
+Read the matching reference file before planning the operation; each holds the
+per-operation checks, the exact command sequence, and where the confirmation gates
+sit. Versions in the reference files are placeholders; fill in real ones.
+
+| Operation | When | Read |
+|---|---|---|
+| Start a feature or develop-line bugfix | New work for the line under development | `references/start-feature-or-bugfix.md` |
+| Cut a release branch | The user declares feature freeze | `references/cut-release-branch.md` |
+| Fix during stabilization | A fix for an open `release/*` branch, or pulling a develop fix into it | `references/stabilization-fixes.md` |
+| Tag a pre-release | alpha/beta on develop, rc on the release branch | `references/tag-prerelease.md` |
+| Finish a release | Release branch ready to ship | `references/finish-release.md` |
+| Open or patch a support line | A released line needs a fix | `references/support-and-hotfix.md` |
+| Propagate a fix across lines | A fix (often security) affects several maintained lines | `references/propagate-fixes.md` |
+
+## Conventions
+
+- Branch names exactly as the strategy doc defines: `feature/<line>/<desc>`,
+  `bugfix/<desc>`, `release/<major>.<minor>.<patch>`, `hotfix/<major>.<minor>.<patch>`,
+  `support/<major>.<minor>.x`, and `merge/<source>-to-<target>` for back-merge
+  branches. Descriptions are lowercase kebab-case, short but meaningful.
+- For `feature/<line>/<desc>`, `<line>` is the in-development `<major>.<minor>`. If
+  the user has not said which line, infer it from context (e.g. the latest pre-release
+  tag on `develop`) and confirm the inference, or ask.
+- PRs via `gh pr create` with explicit `--base` and `--head`, or the web UI. Create
+  only; never merge. Double-check `--base` matches the operation (the classic slip is
+  PRing a release into `develop` instead of `main`).
+- Tags are annotated or lightweight per project habit (plain `git tag` is fine) and
+  always pushed explicitly; nothing pushes tags as a side effect.

.claude/skills/educates-git-workflow/references/cut-release-branch.md

@@ -0,0 +1,47 @@
+# Cut a Release Branch (at Feature Freeze)
+
+A `release/<major>.<minor>.<patch>` branch isolates stabilization of a version from
+ongoing development. Cutting it is what enacts feature freeze: after this, only
+stabilization work goes on the release branch, and `develop` opens up for the next
+version.
+
+Maintainer operation: direct clone only, never from a fork.
+
+## Ask first
+
+- Confirm the user is declaring feature freeze now. Do not cut a release branch as a
+  side effect of some other request.
+- The exact target version (`X.Y.Z`). Do not guess it.
+
+## Per-operation checks
+
+After the universal pre-flight:
+
+- Local `develop` is up to date with `origin/develop`.
+- The target version does not already exist as a tag, locally or on origin:
+  `git tag -l X.Y.Z` and `git ls-remote --tags origin X.Y.Z` are both empty.
+- The branch `release/X.Y.Z` does not already exist on origin.
+- Check for other `release/*` branches still on origin
+  (`git ls-remote --heads origin 'release/*'`). Finished release branches are supposed
+  to be deleted, so finding one means either housekeeping was missed or another
+  release is still in flight. Decide which by checking whether that release's final
+  tag exists: if it does, the branch is a stale leftover, so mention it and suggest
+  deleting it once this cut is done, but do not block on it. If the final tag does
+  not exist, that release looks unfinished; stop and ask, since cutting the next
+  release while the previous one is mid-stabilization is usually a process error.
+
+## Commands
+
+```
+git switch develop
+git pull --ff-only
+git switch -c release/4.1.0
+```
+
+Then, gated:
+
+1. [confirm] `git push -u origin release/4.1.0`
+
+From this point alpha/beta tags stop (those belong to `develop` before the freeze) and
+rc tags happen here. Remind the user that fixes to this release now follow the
+stabilization-fix workflow.

.claude/skills/educates-git-workflow/references/finish-release.md

@@ -0,0 +1,79 @@
+# Finish a Release
+
+Five stages, each gated separately. The shared branches require PRs (rulesets reject
+direct pushes), so the merges happen as PRs that a human reviews and merges in the
+GitHub UI. You create PRs and stop; you never merge them. Expect this flow to span
+multiple turns, waiting on the user at each human step.
+
+Maintainer operation: direct clone only.
+
+## Stage 0: pre-flight and plan
+
+After the universal pre-flight:
+
+- `release/X.Y.Z` exists and local copy is up to date with origin.
+- `main` is up to date with origin.
+- The final tag `X.Y.Z` does not exist locally or on origin.
+- Release notes for the version exist **on the release branch** (check the branch, not
+  the local working tree):
+  `git show origin/release/4.1.0:project-docs/release-notes/version-4.1.0.md` succeeds,
+  and the documentation table of contents references them:
+  `git show origin/release/4.1.0:project-docs/index.rst` contains
+  `release-notes/version-4.1.0`. If either is missing, stop: the release is not ready
+  to ship. The fix is a normal stabilization commit on the `release/` branch adding
+  the notes file and the index entry (release documentation counts as stabilization
+  work); it then reaches `develop` through the back-merge like any other fix.
+
+Present the full five-stage plan with concrete values, then take the stages one at a
+time.
+
+## Stage 1: PR the release branch into main
+
+1. [confirm] `gh pr create --base main --head release/4.1.0 --title "Release 4.1.0"`
+
+Stop. The user (or another maintainer) reviews and merges this PR in the UI. Wait for
+the user to say it is merged; verify with `git fetch origin` and confirm
+`origin/main` now contains the release branch head.
+
+## Stage 2: tag the final release on main
+
+```
+git switch main
+git pull --ff-only
+git tag 4.1.0
+```
+
+2. [confirm] `git push origin 4.1.0`
+
+The pushed tag is immutable and triggers the CI release build. Show the tagged commit
+(sha + subject) in the confirmation. `main` only ever carries final release tags.
+
+## Stage 3: back-merge main into develop
+
+So develop reflects exactly what shipped, including stabilization fixes and
+version-bump commits:
+
+```
+git switch develop
+git pull --ff-only
+git switch -c merge/4.1.0-to-develop
+git merge main
+```
+
+If the merge conflicts, stop and resolve with the user; the back-merge may not be
+automatic. Then, gated:
+
+3. [confirm] `git push -u origin merge/4.1.0-to-develop`
+4. [confirm] `gh pr create --base develop --head merge/4.1.0-to-develop --title "Back-merge 4.1.0 into develop"`
+
+Stop. Human reviews and merges in the UI.
+
+## Stage 4: delete the finished release branch
+
+Only after the back-merge PR is merged, so nothing is lost. The release branch is
+ephemeral; the permanent record is the tag plus the merge commits.
+
+5. [confirm] `git push origin --delete release/4.1.0`
+
+Also delete the local `release/4.1.0` and `merge/4.1.0-to-develop` branches (low
+risk, but mention it).

.claude/skills/educates-git-workflow/references/propagate-fixes.md

@@ -0,0 +1,54 @@
+# Propagate a Fix Across Maintained Lines
+
+A fix (a vulnerability fix especially) usually affects more than one line: several
+`support/*` branches and `develop`. Which lines are affected is the user's decision;
+ask for the explicit list and do not assume. Executing the porting is yours.
+
+Work **oldest affected maintained line first**, then port forward in order, ending
+with `develop`. One direction means no re-doing the fix and no line left behind.
+Cherry-pick is usually cleaner than merge where the surrounding code has diverged.
+
+## Procedure
+
+1. Ask the user which lines are affected. Restate the resulting checklist, e.g.:
+   - `support/3.6.x` (oldest affected)
+   - `support/3.7.x`
+   - `develop`
+2. Land the fix on the oldest line first via the normal hotfix workflow
+   (`references/support-and-hotfix.md`), if it is not already there.
+3. For each newer line in order, port the commit(s):
+
+```
+git switch support/3.7.x
+git pull --ff-only
+git switch -c hotfix/3.7.2          # next patch version for that line
+git cherry-pick <commit-sha(s)>
+```
+
+   Gated, per line:
+   - [confirm] `git push -u origin hotfix/3.7.2`
+   - [confirm] `gh pr create --base support/3.7.x --head hotfix/3.7.2 --title "..."`
+
+4. For `develop`, the port is a `bugfix/*` branch:
+
+```
+git switch develop
+git pull --ff-only
+git switch -c bugfix/<desc>
+git cherry-pick <commit-sha(s)>
+```
+
+   Gated:
+   - [confirm] `git push -u origin bugfix/<desc>`
+   - [confirm] `gh pr create --base develop --head bugfix/<desc> --title "..."`
+
+5. If a cherry-pick conflicts, stop and resolve with the user.
+6. When every line's PR exists, restate the checklist with status per line, so the
+   user can see nothing was missed before they merge. Tagging each line's patch
+   release follows the support-and-hotfix reference, per line, after its PR merges.
+
+## Back-porting
+
+When the fix already exists on a newer line and an older maintained line turns out to
+be affected, the same procedure runs in reverse: cherry-pick down onto the older
+support branch via its hotfix workflow. The checklist discipline is identical.