# Cratis Release Notes

> Use when drafting or reviewing release notes, upgrade guidance or announcements for a specific verified Cratis version. Not for deciding release authority, publishing or selecting a version label.

- Skill: `cratis/cratis-release-notes` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add cratis/cratis-release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cratis/cratis-release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Cratis (https://skillmd.com/u/cratis)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/cratis/cratis-release-notes

---


# 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](../../rules/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 by
  `cratis/release-action`, `(#n)` is what closes the issue), never `Closes`, `Fixes` or
  `Refs` before 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 absolute
  `https://` 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 `## Changed` or `## Removed` bullet (a first
  `## Summary` section 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](../../rules/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:

1. 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 into
   `https://` URLs. Do not invent changes, versions or issue numbers.
2. Publish the corrected text with `gh release edit TAG --notes-file FILE`,
   only when the request authorizes editing that release.
   Read back the body with `gh release view TAG --json body` and 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.
3. 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

1. 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.
2. 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.
3. 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.md` headings such as
   `### 18 to 19`, linked at-a-glance rows, `**Title** — released YYYY-MM-DD`
   metadata, and explicit `**You do:**` actions.
   Check `sync-upgrade-paths.mjs` and an existing guide before changing that
   structure, then verify the generated picker as well as the page.
4. 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](https://wolverinefx.io/guide/migration.html)
and [Marten's migration guide](https://martendb.io/migration-guide.html),
which separate concrete upgrade actions from version-specific release notes.
Their current wording is not authority for Cratis versions or APIs.

