prepare-release

name

prepare-release

description

Prepare parse-display release changes before publishing with a Rust Cargo script when nightly Cargo is available. Use when Codex is asked to prepare a parse-display release, bump parse-display to a requested version, move CHANGELOG.md Unreleased entries into a release section, update parse-display-derive only when it changed since the previous version commit, commit the release prep, and create the release git tag.

Prepare Release

Workflow

1. Extract the target version from the user's request.
   • Accept only an explicit version such as 0.11.0.
   • If the user did not provide a version, do not modify files. Show next-version candidates, ask the user to provide the target version, and end the turn.
   • Prefer using the bundled Cargo script with no version to show candidates:

cargo +nightly -Zscript .codex\skills\prepare-release\scripts\prepare_release.rs

2. Confirm the repository root is the parse-display workspace.

   • Work from the directory containing Cargo.toml, CHANGELOG.md, parse-display/Cargo.toml, and parse-display-derive/Cargo.toml.
   • Inspect git status --short before editing. Do not include unrelated user changes in the release commit.
   • Do not use Python scripts for this workflow.

3. Prefer the bundled Cargo script when nightly Cargo supports -Zscript.

cargo +nightly -Zscript .codex\skills\prepare-release\scripts\prepare_release.rs --dry-run <version>
cargo +nightly -Zscript .codex\skills\prepare-release\scripts\prepare_release.rs <version>

The script updates release files only. It never commits and never creates tags.

In sandboxed Codex environments, cargo +nightly -Zscript may need approval because Cargo writes build artifacts under Cargo's cache directory.

4. If cargo +nightly -Zscript is unavailable, make the same edits manually.
   • Set parse-display/Cargo.toml package version to <version>.
   • Update Cargo.lock's parse-display package version to <version>.
   • Search docs and Rust doc comments for the previous parse-display version and update only active parse-display version references, such as dependency snippets and current-version docs links.
   • Do not update docs.rs links for deprecated features. Deprecated feature documentation must keep linking to the older version where that deprecated feature is still documented.

rg -n '<old-version>|parse-display = "' README.md parse-display parse-display-with

5. Decide whether to update parse-display-derive.
   • Find the previous version commit:

git log --format=%H --extended-regexp --grep "^Version [0-9]+\.[0-9]+\.[0-9]+\.$" -n 1

• Check whether parse-display-derive changed since that commit:

git diff --name-only <previous-version-commit>..HEAD -- parse-display-derive
git status --porcelain -- parse-display-derive

• If either command shows changes, set parse-display-derive/Cargo.toml package version to <version>, set parse-display/Cargo.toml's parse-display-derive dependency version to =<version>, and update Cargo.lock's parse-display-derive package version to <version>.
• If there are no changes, leave parse-display-derive/Cargo.toml, the dependency version, and the lockfile's parse-display-derive version unchanged.

6. Update CHANGELOG.md manually only if the Cargo script was not used.

   • Insert ## [<version>] - YYYY-MM-DD immediately after the Unreleased block, using the current local date.
   • Move every non-empty category body from Unreleased into the same category under the new version.
   • Add only categories with at least one item under the new version.
   • Leave Unreleased with category headings only. Preserve these headings unless the file already uses a different category set: Added, Changed, Deprecated, Removed, Fixed, Performance, Security.
   • Update the compare links at the bottom:
     • Change [unreleased] to compare v<version>...HEAD.
     • Add [<version>]: https://github.com/frozenlib/parse-display/compare/v<previous-version>...v<version> immediately after [unreleased].

7. Verify the result.

   • Inspect git diff -- CHANGELOG.md parse-display/Cargo.toml parse-display-derive/Cargo.toml Cargo.lock README.md parse-display/src parse-display-with/src.
   • Confirm CHANGELOG.md has a non-empty section for the new version and only empty category headings under Unreleased.
   • Run the repository's normal Rust validation when practical, at minimum cargo check --workspace.

8. Commit only the release-prep files.

   • Stage the files changed by the release workflow.
   • Commit with exactly Version <version>.
   • Do not add unrelated worktree changes to this commit.

git commit -m "Version <version>."

9. Create the release tag after the commit succeeds.

git tag "v<version>"

Notes

• Do not create the tag before the release commit exists.
• If the tag already exists, stop and report the conflict.
• If changelog Unreleased has no items, still create the version section only if the user explicitly wants that release; otherwise report that there are no changelog entries to release.