Release notes for the person upgrading
An upgrader wants to know whether their application changes, what will break,
and what to do before installing. A feature list and a list of pull request
titles cannot answer that. This skill writes the communication, not the
release decision. The repository's release workflow owns version intent,
gates, publication and recovery; drafting never authorizes publishing or
editing a release. If the task also includes release planning, select the
separate cratis/methodology/governed-releases profile as needed; that is not
required to draft notes.
Establish the exact subject
Before writing, identify product, tag or candidate version, previous version, artifact/package names, supported platforms, and the audience. Inventory observable changes from the diff, specs, linked issues/PRs, and authoritative product source at that revision. A PR description is published verbatim as release notes in a Cratis repository; follow its current template and the pull-request contract, and confirm that behavior before drafting. Do not turn a draft into a claim about shipped behavior.
For each change, ask: who uses this path, what happened before, what happens now, is action required, and how would they notice? Check changed defaults, serialization/schema/data migrations, runtime and dependency compatibility, deploy ordering, deprecations/removals, and upgrade/rollback limits. Report what was not verified to the requester or in a PR comment; the published note states only verified facts and never says 'not verified'.
Cratis products move together at their seams: the Chronicle kernel and its clients, Arc and Chronicle, Components and Arc. When a change touches a seam, state supported pairings as facts the reader can act on ('Requires Chronicle kernel 19.25 or later'). Which pairings were tested, and against which branch or commit, is evidence for the PR comment. There is no central compatibility matrix to defer to, so the release note may be the only place a reader learns the supported pairings. Where a measurement drove the change, such as how many deployments hit a failure, give the number; never estimate one to add weight.
Write for the right channel
- Exact-version release note (GitHub/PR): in a Cratis repository this is
the merged PR description, published verbatim, so it follows the contract in
pull-requests.md, which holds the full
rules. The ones most often broken: no development write-up (no Overview,
Verification or Test plan headings, no review or provenance notes; those go
in a PR comment);
(#n)at the end of the bullet that delivers an issue and(part of #n)for anything that stays open (in repositories released bycratis/release-action,(#n)is what closes the issue), neverCloses,FixesorRefsbefore a number (also in bold or a link), and no issue reference inside an HTML comment (release-action removes comments before publishing, so the issue is silently not closed; a body that is only a comment counts as empty and GitHub generates the notes); and absolutehttps://links only. Sections are in a fixed order (Added, Changed, Fixed, Removed, Security, Deprecated); within a section, put changes requiring action first, then new capabilities and fixes. State impact and the user's next action in plain language: state an upgrade action in its## Changedor## Removedbullet (a first## Summarysection or an unheaded lead paragraph, not both, may mention it too). Do not list internal refactors or specs that change nothing users observe. For a user-visible fix, a sentence of root cause and of what now guards against a regression, stated as observable behavior rather than a list of specs, is user-facing: it tells the reader whether to trust the fix. Credit an external contributor by name or handle and say what they did, unless they asked not to be named. - Migration guide (durable product docs): a compact old behavior → new behavior → required action table for each affected upgrade path, followed by source-verified before/after code or commands. Distinguish required migration from optional cleanup, name sequencing for schema/data changes, and explain escape hatches with their cost or expiry. If no action is needed, state why and for whom, rather than implying it for everyone. State the table's scope and its known exclusions, so a reader who does not find their API knows whether it was assessed. Do not infer backward compatibility for APIs or configurations that were not assessed.
- Announcement or blog post: explain the motivation and show a small realistic success, then link to the exact-version note and migration guide. It is not a second independent changelog. Do not claim personal experience on behalf of a named author without their review.
Keep the release note concise enough to scan, but do not compress away the boundary that makes a change safe to adopt. One item can follow this shape:
Applications that run [workflow] on [affected versions] may observe [symptom]. In [new version], [new behavior]. [Action] before upgrading; [unaffected path] does not need to change. [Migration guide].
That is a checklist for facts, not a template to repeat word-for-word across items. Use descriptive headings, meaningful links, and natural sentence rhythm.
A no-release PR body still follows this contract. Its (#n) closes nothing
because no release runs, so the issue is closed separately, and only when the
request includes that effect; never imply automatic closing (see the issue
section of pull-requests.md).
For every pull request, write the body file in a step of its own before
gh pr create --body-file.
Repair an already-published release
Only when asked to fix a release that violates the contract:
- Read the published body (
gh release view TAG --json body) and the merged PR. Keep the facts; remove headings, review and verification lines, internal status and closing keywords, and turn relative links intohttps://URLs. Do not invent changes, versions or issue numbers. - Publish the corrected text with
gh release edit TAG --notes-file FILE, only when the request authorizes editing that release. Read back the body withgh release view TAG --json bodyand compare it with the corrected text. If it differs, correct and repeat the authorized edit and readback, or report the blocker rather than claiming the repair succeeded. - In a repository released by
cratis/release-action, editing a release does not re-run release-action, so an issue that a(#n)would have closed stays open. For each one, confirm the release actually delivered it. Close it by hand with a comment naming the release only when the request covers closing issues; otherwise list the issues as a proposal. Leave an issue open when the release only partly delivered it.
Release-action batching and recovery
Requires release-action 1.5.1 for corrected pending-major hotfix handling; check the workflow's uses pin, or keep immediate releases on the older contract.
release-window defaults to 0 (one
release per PR); a positive minute window batches pending merges once the oldest
is old enough. The highest intent wins, notes merge by section with one combined
## Summary, and delivered (#n) issues still close. Reference definitions are
preserved; duplicate labels keep the first definition and warn. Missing intent
labels warn but are not permission to omit required PR labels.
hotfix-labels defaults to hotfix and bypasses the window. With a pending major,
only the merge run for the hotfix fails; scheduled/other merge runs warn and leave
the batch pending. A manual run without a version releases everything pending;
obtain the required human major confirmation first. Inspect pull-requests and
reason (batched or nothing-pending) rather than assuming every successful
run released. Never turn on batching just to clear a queue without authorization.
A release-creation 403 caused by workflow drift names the recovery: dispatch the publish workflow from the current default branch with the PR's release notes. Re-running the stale commit does not fix this. Other 403s keep their original cause; do not treat every permission failure as workflow drift.
Before re-running a cancelled publish, check
git merge-base --is-ancestor <merge-commit> <latest-release-tag>. If it is an
ancestor, a release already contains the change, so do not cut another version.
The tag alone does not prove it shipped: a release can be created before its
publishing jobs run. Confirm that the containing release's publish run completed
every publishing job and its packages exist before reporting it shipped;
otherwise recover that version's publishing rather than releasing again.
Verify before handing over
- Reconcile every version, affected range, capability and API against the release tag or exact candidate and published artifact when available; verify each reference and link. A blog post or release summary is a pointer to source, not proof that a compatibility issue is resolved.
- Have a reader of the affected integration check that the instructions are actionable. Exercise upgrade commands and compile before/after examples with stated versions when feasible; use cratis-technical-examples for the example workflow.
- Recheck the evergreen migration guide after release. Remove 'upcoming',
prerelease pins and obsolete workaround language only after verifying the
final tag. Separate live guidance from a historically accurate note for an
older release. Preserve the owning site's machine-consumed guide format:
Cratis's upgrade picker reads
upgrading/major-versions.mdheadings such as### 18 to 19, linked at-a-glance rows,**Title** — released YYYY-MM-DDmetadata, and explicit**You do:**actions. Checksync-upgrade-paths.mjsand an existing guide before changing that structure, then verify the generated picker as well as the page. - Name the checks actually run and the combinations not checked to the requester or in a PR comment, never in the published note. Do not imply that a green docs build proved an upgrade safe.
The pattern is informed by Wolverine's migration guide and Marten's migration guide, which separate concrete upgrade actions from version-specific release notes. Their current wording is not authority for Cratis versions or APIs.