Rigor Release Prep

Rigor Release Prep

Follow this workflow when preparing a new rigor gem release.

All commands MUST run through the Flake per AGENTS.md. The examples below include the full nix develop --command prefix so each line is directly runnable from outside the Flake shell. Inside the Flake shell, drop the prefix.

Branch: release/x.y.z

Release work happens on a dedicated release/x.y.z branch, not directly on master (ADR-50). Cut it from an up-to-date master:

git switch master && git pull
git switch -c release/x.y.z

Every step below — the metadata edits, the local verify, the version-bump commit — lands on this branch. Pushing it runs release-gate.yml (perf benchmark, gem-build validation, OSS-corpus sweep — advisory until it is promoted to a required check), the comprehensive release gate the normal master CI does not (see "Push and watch the release gate" below). The base CI gate (ci.yml) runs on the release PR you open next, via its pull_request event — ci.yml triggers on push to master only, so a release branch is not double-run (push + pull_request) the way it would be if release/** were also a push branch.

Update Release Metadata

Decide the next semantic version first, then update all versioned files together.

Update these files:

• CHANGELOG.md
• lib/rigor/version.rb
• Gemfile.lock (regenerated by bundle install after the version bump)
• README.md (the ## Status line — version + date; see "Refresh the README status" below)

Seal the [Unreleased] entries — the mandatory rewrite step

Do this first, before the mechanical version-heading move below, and treat the entries — not the version bump — as the deliverable of this skill. The intended state is that every fragment was already written release-style at landing (docs/agents/contribution-flow.md § "Release Cadence"), so this step is mostly cross-entry consolidation: fold several commits' entries into one user-recognisable change, reorder, dedupe, and split any merge artefacts — work that needs the cycle-wide context only release time has. In practice the section also accumulates commit-style drift (detailed, implementer-facing, multi-sentence, em-dash run-ons) that landing-time discipline missed, so this step is also the safety net that rewrites that drift into release-style before the version is sealed — it is not, however, a licence to skip landing-time quality and rewrite commit prose wholesale at the cut.

This is the highest-value, most-skipped step in a release. A release whose CHANGELOG still reads like commit messages is not done, even if every versioned file agrees and make verify is green — prose quality is invisible to make verify, so nothing downstream will catch a skipped rewrite. It is the one step silently lost when the mechanical steps around it get done; do not let "the entries are already there" stand in for reviewing and consolidating them.

Consolidate changelog.d/ fragments before anything else. Entries land as changelog.d/<section>/<slug>.md fragments (ADR-105), so the seal starts by moving every fragment's line(s) under the matching ### section of [Unreleased] (creating sections in Keep a Changelog order as needed) and deleting the fragment files (git rm). After this, changelog.d/ contains only its README.md, and the enumeration below runs over the consolidated [Unreleased].

CHANGELOG.md follows Keep a Changelog 1.1.0. This skill is the canonical statement of the entry rules — docs/agents/contribution-flow.md carries only the landing-time one-liner, because the full set matters to a session writing an entry, not to every session. The rules:

• One sentence per top-level bullet. One period, no em-dash clauses, no run-ons. Self-contained enough to understand without the body.
• One LINE per bullet, never column-wrapped. This section is extracted verbatim as the GitHub Release body, and GitHub renders a newline inside a paragraph as <br> — a wrapped entry renders ragged. Same rule for any PR / issue / comment / wiki text (docs/agents/contribution-flow.md § "Commits and GitHub Markdown").
• Subsystem label prefix: **[rigor check]**, **[engine]**, **[plugin contract]**, **[plugins/rigor-foo]**, etc.
• User-facing only. Cut internal implementation detail — class renames, RBS plumbing for the analyzer's own surface, test/spec additions, coverage counts, refactor-only plugin migrations. Ask of each: "would a user care if they weren't reading the source?" If no, delete it.
• Supplementary detail goes in child items ( - …), two to three sentences max, one topic each.
• A changelog entry is not a commit message: many commits may collapse into one entry, and one fat [Unreleased] line may split into several.
• Link the PR that landed it, as a full markdown link at the end of the bullet: ([#170](https://github.com/rigortype/rigor/pull/170)). Put it on the child item instead when one bullet consolidates several PRs and each detail traces to a different one. Add the reporting issue too when there is one, and thank you @handle! for an outside report. The link is how a user gets from "what changed" to the detail.
  • The full form, never a bare #170. This section is extracted verbatim as the GitHub Release body (rake release:github), where GitHub autolinks a bare #170 — but the same text is also CHANGELOG.md rendered from the repo tree, where it is not autolinked and stays dead text. Only the markdown form works in both, which is why every link already in the file uses it.
  • Omit it when there is no PR. A small docs-only change can land straight on master (docs/agents/contribution-flow.md § "Branches and pull requests"), so it has a commit and no PR. Do not invent one, and do not link the commit instead — if the change is user-facing enough to have an entry, the entry is the record.

The three shapes to reject on sight:

# ✗ two sentences joined by an em-dash
- **[plugins]** All bundled plugins now ship inside the `rigortype` gem — `require "rigor-foo"` resolves without any workaround. Activate with `plugins: [rigor-foo]`.

# ✗ internal implementation detail as a child item
  - Individual gemspecs inside `plugins/` are removed; the plugin family ships as a single unit.

# ✗ commit-message prose instead of a user-meaningful description
- **[baseline]** Fix `group_for_baseline` to normalise paths to relative before building bucket keys.

Each is fixable in place — split the em-dash into a bullet plus a child item, delete the internal detail, and restate the third as what a user can now do:

- **[rigor baseline generate]** Fixed a crash when `plugins:` entries in `.rigor.yml` were plain strings.

- **[plugins]** All bundled plugins now ship inside the `rigortype` gem, so `require "rigor-foo"` works without any `RUBYLIB` or `Gemfile` workaround.
  - Activate any plugin with one line in `.rigor.yml`: `plugins: [rigor-foo]`.

Procedure — the enumeration is what makes the rewrite un-skippable, so do not shortcut it:

1. Pull the cycle's merged PRs up front, so linking is a lookup rather than a recall. Derive the range from the previous release's tag, never from its ## [x.y.z] - DATE heading:

   git log --oneline --merges vX.Y.Z..HEAD | grep -oE '#[0-9]+'

   The heading date is a trap. It is a local-time date, and gh pr list --search "merged:>=DATE" filters in UTC, so every PR merged between the tag and local midnight falls outside the query. The tag range is exact, offline, and has no timezone to get wrong.

   Keep the list beside you for step 4. It is also a completeness check: a PR in it with no entry anywhere is either a user-facing change nobody wrote up, or correctly internal — decide which, do not skip past it.

2. Read the entire [Unreleased] block. For each top-level bullet, explicitly classify it: release-style (leave) or commit-style (rewrite).

3. Rewrite every commit-style bullet — lead sentence to one clause, move the "why / how it works / measured numbers" into a child item, delete internal detail outright.

4. Check every bullet already carries its PR link, against the step-1 list. The landing rule requires the link, so this is verification, not authoring: a bullet missing one means the landing rule was skipped, and you are now paying the reconstruction cost this step exists to avoid. Match on the change, not the title wording — a bullet that consolidates several PRs links each on the child item it belongs to. Leave a bullet unlinked only when its change genuinely had no PR (a Markdown-only push to master).

5. Watch for merge artefacts: two entries accidentally glued into one bullet (a stray second **[label]** mid-sentence, an env-var description hanging off an unrelated entry). Split them. CHANGELOG.md is merge=union (.gitattributes), which trades insertion-order conflicts for one artefact you must look for here: a duplicated ### heading, where two branches each opened the same section. Merge the two, keeping Keep a Changelog's order. spec/docs/changelog_conformance_spec.rb fails on it, so a missed one is caught rather than shipped — but catching it at the cut is cheaper.

6. Re-read the sealed section top-to-bottom as a user would. If any top-level bullet still has two sentences or an em-dash clause, it is not done.

Worked collapse (a real shape this repo produces):

# ✗ commit-style, as it lands in [Unreleased]
- **[engine]** RBS-complete ancestor resolution — `rigor check` now resolves a
  Ruby subclass's inherited calls against an allow-listed RBS-only ancestor, so
  misuse is caught. Previously a Ruby class subclassing an RBS-only class
  resolved every inherited call to `Dynamic[Top]` because the dispatcher
  short-circuited when the subclass name is absent from the RBS environment, so
  no ancestor walk ran (the edge was recorded in `Scope#discovered_superclasses`
  but never consulted by `RbsDispatch`). The fix threads the analysis `scope`
  into `RbsDispatch.lookup_method` and resolves against the ancestor's RBS ...

# ✓ release-style, after the rewrite
- **[engine]** RBS-complete ancestor resolution: `rigor check` now resolves a
  Ruby subclass's inherited method calls against an allow-listed RBS-only
  ancestor, so a typo'd or renamed contract call such as `manifest.bogus` on a
  plugin fires `call.undefined-method` ([ADR-43](docs/adr/43-rbs-complete-ancestor-resolution.md)).
  - The allow-list is the false-positive boundary: a non-allow-listed ancestor
    (e.g. `ActionController::Base`) keeps the `Dynamic[Top]` fallback, so a
    controller calling a method an incomplete gem RBS omits is never flagged.

(ADR-43 predates public development and landed by direct commit, so it has no PR to link — the omission above is the rule working, not a lapse. A change that did go through one reads … so the scan no longer re-runs per file ([#74](https://github.com/rigortype/rigor/pull/74)).)

Write the release summary

Immediately under the new ## [x.y.z] - YYYY-MM-DD heading, before the first ### section, write a short prose summary — a few simple sentences (≈3–4), in the CHANGELOG's language (English) — that gives a reader the themes of the release before the itemised entries. It complements the bullets: the bullets are the precise "what changed", the summary is the narrative "what this release is about".

• Lead with the dominant theme (the biggest performance thread, the headline feature, …), then name one or two secondary threads, then close with a short "other fixes" clause — mirroring the bullets' weight.
• Keep it short. It is a lead, not a recap of every bullet — one clause per theme, no exhaustive enumeration.
• Link sparingly, using the file's existing repo-relative convention ([ADR-46](docs/adr/46-…), [the Elixir v1.20 review](docs/notes/…)) — a pointer to the driving ADR / note for a theme, not a link per bullet.
• It is user-facing prose: the same "would a user care?" bar as the bullets; no internal class names or measured-number dumps (those live in the bullets and their child items).

Example shape (the 0.1.17 summary):

v0.1.17 focuses on making analysis of real projects markedly faster — an incremental analysis cache, an unchanged-project fast path, and a large allocation reduction on big Rails apps. Inspired by the Elixir v1.20 type system, control-flow narrowing is strengthened for several methods. It also folds Data.define value objects to precise types and adds new clause-reachability and conformance diagnostics; fixes include a block-parameter binding crash and a pathological route-helper re-read.

Refresh the README status

Update the ## Status block in README.md to the new release as part of this release, not as a later follow-up. Because publish runs immediately after the PR merges (the next section), the README on master is never a window ahead of a published gem — updating it here means the moment the release lands, the front page already names the version RubyGems serves.

• Change Current release: **vX.Y.Z** (YYYY-MM-DD) to the new version and date. For a patch/minor within the same leading-digit cycle that is the whole edit — the surrounding prose (the 0.x line description, the compatibility-surface and hardened-against clauses) is cycle-stable, so leave it untouched.
• A leading-digit bump (or a release that changes the cycle's story) may also need that surrounding prose refreshed — reread the block and update any clause the release makes stale.
• Keep this in the Bump up version to x.y.z commit alongside the other versioned files; it is release metadata, not a separate docs pass.

Release mechanics

• Add a new ## [x.y.z] - YYYY-MM-DD section immediately below [Unreleased].
• Open it with the release summary above, then the ### Added / ### Changed / ### Fixed sections.
• Use Keep a Changelog section headings verbatim: Added, Changed, Deprecated, Removed, Fixed, Security. Do NOT inline a description into the heading (### Added — feature X is wrong; the heading is just ### Added). Do NOT use #### sub-headings inside a version block. There is no Performance / Internal / Documentation section — a speed-up is Changed, a docs correction is Fixed. Say what it is in the entry, not in a heading of your own invention; spec/docs/changelog_conformance_spec.rb gates this.
• Group the same kinds of changes under the same heading — one section per type per release, in the Keep a Changelog order above (Added first, Security last). Both are gated.
• Preserve the release date in every version heading and the Keep a Changelog / Semantic Versioning notes at the top of CHANGELOG.md.
• Update the [Unreleased] compare link and add the new release link at the bottom of CHANGELOG.md. Compare links target https://github.com/rigortype/rigor/compare/....
• Bump Rigor::VERSION in lib/rigor/version.rb to match the new release.
• Run bundle install after the version bump so Gemfile.lock records the new rigortype (x.y.z) revision; commit the regenerated lockfile alongside the version bump.
• Keep the release commit message in the form Bump up version to x.y.z.

Archival rule (mandatory check)

Before bumping the version, check whether the new release is the first release after a leading-digit bump. The archival rule:

At the first a.b.c release whose (a, b) pair matches the most recent release but DIFFERS from the most recent archive's prefix, move the previous-digit range out of CHANGELOG.md into a new docs/CHANGELOG-<old-prefix>.md archive file.

Worked example: the rule fires at 0.1.1 because (0, 1) matches 0.1.0 (the previous release) but differs from the most recent archive (none yet), so 0.0.x moves to docs/CHANGELOG-0.0.x.md. The next archival fires at the first 0.2.x post-bump release (0.2.1), which moves 0.1.x to docs/CHANGELOG-0.1.x.md.

When the rule fires:

1. Create docs/CHANGELOG-<old-prefix>.md with a header explaining what's in the file and a back-link to CHANGELOG.md. Use the archive built at 0.1.1 as the template — the explanatory header on docs/CHANGELOG-0.0.x.md is the reference shape.
2. Move the entire ## [a.b.c] - YYYY-MM-DD block for every version in the range, plus the matching [a.b.c]: https://... reference links from the bottom of CHANGELOG.md, into the archive.
3. Update CHANGELOG.md's top-of-file "Older release notes are archived" pointer list to include the new archive file.
4. Verify the active CHANGELOG.md now holds only [Unreleased] and the most recent leading-digit cycle (a.b.0 plus any later a.b.c).

The rule keeps the active CHANGELOG.md small enough to read top-to-bottom without scrolling fatigue while preserving every release note's full text and link addressability.

Verify the Release

Run before committing:

nix develop --command make verify
nix develop --command git diff --check

make verify is the CI-equivalent gate (tests, lint, check, and check-plugins). git diff --check catches whitespace mistakes in the release diff.

Overlap it with the sealing rather than queueing behind it. make verify is ~170 s of wall time that the prose work does not depend on, and the release commit touches no lib/. Land the code-affecting edits first — version.rb, then bundle install — start make verify in the background, and seal the [Unreleased] entries while it runs. The gate must still see the last edit: a CHANGELOG.md tweak made after a green verify can turn CI red, and make docs-check does not cover the changelog conformance spec. So after the final edit, re-run the two cheap gates that the prose can actually break:

nix develop --command \
  bundle exec rspec spec/docs/changelog_conformance_spec.rb
nix develop --command make docs-check

That preserves the after-the-last-edit invariant at a fraction of a full rerun.

Also build the gem to confirm the gemspec is still valid for the bumped version:

nix develop --command gem build rigortype.gemspec

The build produces rigortype-x.y.z.gem in the working tree. Delete it before committing — built gems must not be checked in.

If make verify requires formatting fixes or other non-version cleanup, commit that work separately before creating the version-bump commit. Do not fold release verification cleanup into the Bump up version to x.y.z commit.