Release Notes

Release Notes

The release workflow publishes with GitHub-generated release notes, so every MeshLLM release starts life as one flat ## What's Changed list. A normal minor release carries a few hundred entries in merge order, which buries the handful of changes a reader actually needs. The release_notes job in release.yml regroups that list into Keep a Changelog 1.1.0 sections right after publication.

This skill formats notes that already exist. It does not decide release readiness or build the change inventory from source; that is release-validation.

Ground Rules

• Move entries; the only edit is the type prefix. The renderer strips a known conventional type from the front of a subject and sentence-cases what follows, because the type already chose the section and repeating it reads inconsistently beside entries that never had one. A subject with no recognised prefix is left exactly as written -- an unrecognised word: may be part of the sentence, as in "Durable KV prefix cache: agent prefixes survive eviction". Nothing else about a subject changes.
• Never touch the credit. The by @<author> in <url> tail is copied through byte for byte, and the set of referenced pull requests is the invariant every gate checks.
• Never drop an entry. Every merged PR credits a contributor, including the CI and build churn. Noisy entries collapse into ### Internal, never deleted.
• Recover an entry GitHub could not credit. A batch of pull requests merged into a staging branch and rebased into the release is credited once, to the roll-up. The link pass adds the missing entries back in the roll-up's own format, so the reader sees the fixes rather than the vehicle that carried them. Adding is the only direction: the published set is a floor.
• Keep the tail. ## New Contributors and the **Full Changelog** link stay exactly as GitHub generated them.
• Never guess a section. An entry the commit metadata cannot place goes to ### Other changes. A wrong section is worse than an honest unsorted one, and misfiling a security fix as a routine fix is the worst case.
• Editing a published release is a public change. Outside the release job, show the regrouped body and get explicit approval before gh release edit.

How The Pipeline Works

Three passes, in this order. The first two always run and together always produce a publishable body; the third is best-effort.

flowchart TD
    A["Release published"] --> B["Capture GitHub's flat list"]
    B --> L["Link commits to pull requests<br/>recover what GitHub credited to a roll-up"]
    L --> C["Classify by commit type<br/>feat → Added · fix → Fixed · ci → Internal"]
    C --> D{"Agent reachable?"}
    D -- no --> F["Deterministic notes"]
    D -- yes --> E["Agent reviews the plan"]
    E -- valid --> G["Reviewed notes"]
    E -- "invalid or timed out" --> F
    F --> P["Publish"]
    G --> P
    P --> V["Verify the same pull requests"]

One rule gates every step after the link pass: the set of referenced pull requests must not change. Sections move, subjects lose their type prefix, but no PR is dropped, duplicated, or invented, and author credit is copied through untouched. The link pass is the one step allowed to grow that set, and it is gated the other way: it may add entries and may never drop one. Nothing publishes unless both hold.

1. Link pass (authoritative, best-effort calls)

scripts/release-notes-link.py pairs each commit in the range with the pull request that carried it. The (#N) suffix a squash merge leaves on the subject is authoritative and free; a commit without one costs a repos/{repo}/commits/{sha}/pulls lookup, and a commit the API cannot place is left unlinked rather than guessed at.

That pairing repairs two things GitHub's generated list cannot express:

• a commit that reached the branch without the suffix now reaches its entry, so the classifier can read its type instead of dumping it in Other changes;
• a pull request whose commit is in the release but whose entry GitHub never published is credited beneath the roll-up that carried it in. v0.76.1 shipped fifteen fixes behind a single Fixed entry before this existed.

Both are bounded: --api-budget caps the lookups, and every failed call falls back to the behaviour the pipeline had before the pass existed.

2. Deterministic pass (authoritative)

scripts/release-notes-classify.py reads the canonical squash-merge commits between the comparison base and the tag, and maps each entry by its Conventional Commits type:

Two rules override the type. A tooling scope — ci, release, build, deps, xtask, bench, just — is Internal whatever the type, because a fix(ci) repairs CI rather than the product. A Release-Notes: <Section> commit trailer wins outright, and is the escape hatch when the type cannot express the change.

scripts/release-notes-regroup.py then renders the plan, refusing unless it covers the body exactly.

3. Agent review pass (optional, best-effort)

scripts/release-notes-generate.sh probes for a reachable agent and, only if one answers, asks it to review the deterministic plan — chiefly the Other changes entries and any security-relevant fix committed as a plain fix. Its output goes through the same validation and entry-set gate as the deterministic plan.

The agent is optional by construction. Missing CLI, absent credentials, failed probe, exhausted quota, blown time budget, unparseable plan, or a plan that fails validation each log a reason and keep the deterministic notes. None of them fail the job. AGENT_MODEL is unset by default, so the pipeline ships deterministic-only until a runner provides the CLI and credentials.