Release

Release

Prepare a new release by bumping versions and updating the changelog — or, with the review option, run a pre-release audit that surfaces inconsistencies and improvement ideas without changing anything.

Input

The argument selects the mode:

• review (or "release review", "review for release", "pre-release review") — run the Release review below. This is advisory only: it bumps nothing, edits no files, and makes no commit. Run it before cutting a release.
• A version string (e.g. 1.2.0) — run the Version bump flow (the numbered steps). If no argument is given and the intent is clearly to cut a release, ask which version.

If the user asks for a release review and then to proceed, run the review first and the version bump second.

Release review

A pre-release audit. Run it before cutting a release — especially a major version, since a major bump is the only window in which breaking API changes are acceptable. It does not bump versions, edit the changelog/README, or commit anything; it produces a report. It kicks off two complementary reviews, then synthesizes them.

A. Consistency review

Audit the public surface for lingering inconsistencies across the whole crate, not just the latest diff. Scope it to everything accumulated since the last released version.

Establish the baseline with plain, side-effect-free commands — run each separately rather than nesting a $(…) command substitution, so each invocation can be statically verified and auto-approved (a $(git …) substitution defeats static analysis and forces a prompt):

git describe --tags --abbrev=0    # last released tag
git tag --sort=-creatordate       # full tag list, newest first
git log --oneline -20             # recent commits — find the last "Release"/"release" commit

Read the last-released version off the result, then diff against it explicitly, e.g.:

git diff v1.1.0..HEAD --stat      # substitute the real last-released ref

Tags in this repo are unreliable — they have lagged the crate version before (e.g. git describe returned v0.8.0 while the crate was at 2.0.0). Do not trust the tag blindly. Cross-check it against the […] version headings in CHANGELOG.md and the most recent Release/release commit in the log; if they disagree, use the last actually released commit (the one matching the newest released CHANGELOG section) as the diff baseline, not the stale tag.

Check for:

• Naming parity — do sibling types/methods share vocabulary? (e.g. max_size vs size, with_* constructors, try_with_* fallible variants, cache_* method prefixes). Flag any odd-one-out.
• Builder / constructor symmetry — does every store with a builder expose the same setters where they make sense? Does each family (plain vs sharded, LRU vs TTL) have parallel constructors?
• Trait-method parity — do the sync / async / sharded variants of a trait expose the same method set with consistent signatures (&self vs &mut self)?
• Feature-gate symmetry — is each public item gated behind exactly the features it needs, and are paired items gated consistently?
• Doc / CHANGELOG / migration-guide alignment — do the docs, the [Unreleased] CHANGELOG section, and the migration guide accurately describe the shipped API (named types, signatures, attribute names, feature gates)?

Delegate the correctness/idiom sweep to a pr-code-reviewer sub-agent fed the full release diff, and reason through the cross-type parity items yourself — they need a whole-surface view the diff alone does not give.

B. API examination review

Run the consumer-experience-review skill. It builds a throwaway external consumer that depends on the crate the way a real user would and surfaces API gaps, naming inconsistencies, trait-import friction, and feature-flag dead-ends with compiler-verified evidence. This is the authoritative "what would a new user trip over" pass.

C. Synthesize the report

Merge both reviews into a single report. Apply no change — this mode is advisory. Produce:

1. Lingering inconsistencies — a flat list of every inconsistency found, each with a file:line (or API path) and a one-line description.
2. Recommended changes, split by impact:
   • Breaking — changes that alter the public API (renames, signature changes, removed items, new required trait methods). For each: what to change, why it improves the library, and the migration cost. Mark these "land now or wait for the next major" — a major-version release is the only non-breaking window to make them.
   • Non-breaking — additive or internal changes (new constructors, doc fixes, new re-exports, deprecations that keep the old path working). For each: what to change and why.
3. Recommendation — is the library consistent enough to release as-is, or are there high-impact items that should land in this version first? Be explicit about which breaking items, if deferred, are stuck until the next major.

After presenting the report, ask whether to address findings first or proceed to the version bump below.

Version bump

These numbered steps are the default mode — run them when the argument is a version string, or after a release review once the user opts to proceed.

1. Determine which crates to bump

This repo has three crates:

• cached — always bumped
• cached_proc_macro — bump if this PR/branch touched cached_proc_macro/
• cached_proc_macro_types — bump only if this PR/branch touched cached_proc_macro_types/

Run the helper script to detect which crates need bumping:

.agents/skills/release/detect-crates.sh

This outputs one crate name per line based on git diff origin/master. Its diff base is only as good as the branch, so cross-check against the last release tag when the branch has been merged into already, e.g. git diff --name-only v3.0.0..HEAD -- cached_proc_macro/.

A subcrate that did not change stays at its current version, and its [dependencies.*] pin in the root Cargo.toml stays with it. bin/check-versions.sh does not require the three crates to move together; it requires each pin to equal that subcrate's own package version, and it forbids a stable root depending on a pre-release subcrate. A cached-only bump is normal and has shipped before ([2.0.2], [0.58.0]). Do not bump a subcrate just to keep the numbers aligned: that publishes a new version of an unchanged crate.

2. Update Cargo.toml versions

Files to update (only for crates being bumped):

Cargo.toml (the cached crate):

• [package] version → new version
• [dependencies.cached_proc_macro] version → new version (if bumping proc_macro)
• [dependencies.cached_proc_macro_types] version → new version (if bumping proc_macro_types)

cached_proc_macro/Cargo.toml:

• [package] version → new version (if bumping proc_macro)

cached_proc_macro_types/Cargo.toml:

• [package] version → new version (if bumping proc_macro_types)

Use precise string replacement — do not change dependency versions for third-party crates.

3. Update CHANGELOG.md

• Replace ## [Unreleased] with ## [X.Y.Z / cached_proc_macro X.Y.Z] (include only the crates being bumped in the heading — omit cached_proc_macro_types if it is not bumped)
• Add a fresh ## [Unreleased] section above the new version heading
• The changelog must always have an [Unreleased] section at the top

4. Create or update migration guide

Every release requires a migration guide in docs/migrations/ named PREV-to-X.Y.Z.md (e.g. 1.1-to-1.2.md). If there are no breaking changes, the guide still must exist and must state there are no breaking changes.

Migration guides are written for agent consumption: terse, mechanical, grep-friendly. Required sections:

• Versions header line
• Breaking changes — one subsection per change with Detection (what to grep/search for) and Action (exact code transformation). If none, write "None. This release is purely additive."
• New APIs — additive changes; note the feature gate if any
• Required Cargo.toml change — exact before/after snippet
• VERIFY — the cargo build / cargo test commands needed to confirm a successful migration, plus any expected new compile errors and their fixes

See existing guides in docs/migrations/ for the established format.

If the guide for this version already exists (e.g. was drafted ahead of the release), review it against the final diff and update any stale type names, method signatures, or behavior descriptions.

5. Regenerate README

cargo readme --no-indent-headings > README.md

6. Verify

cargo check --no-default-features --features "proc_macro,time_stores"

Fix any compilation errors before proceeding.

7. Commit or amend

If there is already a single commit ahead of master on this branch, amend it:

git add Cargo.toml cached_proc_macro/Cargo.toml cached_proc_macro_types/Cargo.toml CHANGELOG.md README.md
git commit --amend --no-edit

Otherwise create a new commit:

git commit -m "release: bump version to X.Y.Z"

Do not add a Co-Authored-By line.

8. Report

Tell the user:

• Which crates were bumped and to what version
• Whether cached_proc_macro_types was left unchanged and why
• That README was regenerated
• The resulting commit SHA

9. Stop here

Preparing the bump is the whole job. Do not tag, do not cargo publish, and do not run bin/tag-release.sh or bin/publish.sh. .github/workflows/release.yml does all of it once the version bump lands on master: it publishes in dependency order, tags, and creates the GitHub release. Merging the bump is the release.

So do not report tagging or publishing as outstanding work, and do not offer to run either by hand. If the user asks whether a release went out, check it rather than assuming:

gh run list --workflow=release.yml --limit 3

A run can also be sitting on the environment: release approval gate, which looks identical to nothing having happened. Running the bin/ scripts locally is a fallback for the case where Actions cannot run them at all (an outage, or a run that died in a way gh workflow run release.yml --ref master cannot retry), not a normal step.