release-rust-srec

name	release-rust-srec
description	Prepare a new rust-srec application release end to end — pick the next semver version, bump the workspace version, promote the staged unreleased.md notes into versioned en+zh release-notes pages, reset unreleased, refresh the release-notes index/sidebar/GitHub-body, and emit the rust-srec-vX.Y.Z tag command. Use when asked to cut, prepare, plan, or draft a new rust-srec release or version bump.

Release rust-srec

Prepares a rust-srec application release: version bump + localized release notes + GitHub release body, ready for the maintainer to tag. This is a docs-and-version task — it does not publish. Tagging/pushing is the maintainer's call; never tag or push unless explicitly asked.

Source of truth

• Version: root Cargo.toml [workspace.package].version. It flows to rust-srec/Cargo.toml and rust-srec/src-tauri/Cargo.toml (both version.workspace = true) and to Tauri via Cargo fallback. Never hand-edit those downstream files.
• User-facing notes: rust-srec/docs/{en,zh}/release-notes/unreleased.md — the running draft of changes since the last release. Promote this; do not re-derive notes from raw commit subjects.
• Tag scheme: rust-srec-vX.Y.Z (per-package). Do not use bare vX.Y.Z — those are legacy tags from an unrelated lineage. strev/mesio have their own strev-v* / mesio-v* tags.

Steps

1. Pick the next version

• Last release: git tag --list 'rust-srec-v*' --sort=-v:refname | head -1.
• Review changes: git log --no-merges <last-tag>..HEAD.
• Semver: fixes/reliability/dependency bumps only → patch; a new user-facing feature → minor; a breaking change or a migration that needs user action → major. rust-srec's 0.3.x line has stayed patch-level for reliability follow-ups.

2. Verify the unreleased draft is accurate

• Confirm every item in unreleased.md landed after the last tag: git show <last-tag>:rust-srec/docs/en/release-notes/unreleased.md should be the empty shell ("No staged changes yet…"). See which commits added the items with git log <last-tag>..HEAD -- rust-srec/docs/en/release-notes/unreleased.md.
• Never ship an item already announced in the previous vX.Y.Z.md.
• Cross-check headline items against real commits (e.g. a "pipeline waits for X" note should map to a fix(pipeline) commit touching rust-srec/src/...). An item with no backing change since the tag is a red flag — investigate before including it.

3. (Optional) Plan and draft with a Workflow

For a thorough pass, run a multi-agent Workflow: one agent categorizes commits and recommends the bump; parallel agents draft the en page, the zh page, and the GitHub body; a final agent adversarially verifies en↔zh consistency and that every claim traces to unreleased.md or a commit. Draft agents can write the vX.Y.Z.md pages directly (the bump script in step 4 preserves files that already exist).

4. Bump version + scaffold docs

node scripts/bump-rust-srec-version.mjs <X.Y.Z> --docs --dry-run   # preview
node scripts/bump-rust-srec-version.mjs <X.Y.Z> --docs             # apply

The script:

• sets Cargo.toml [workspace.package].version;
• runs cargo update --workspace so Cargo.lock carries the new rust-srec / rust-srec-desktop versions — required: release CI builds with --locked and fails on a stale lockfile (run cargo update --workspace by hand if you ever bump the version without the script);
• creates rust-srec/docs/{en,zh}/release-notes/vX.Y.Z.md only if absent (pre-written pages from step 3 are preserved);
• moves the previous "Latest release" entry into "Archive" in both index.md;
• inserts vX.Y.Z into the VitePress sidebar (.vitepress/config.mts) for both locales;
• bumps version pointers in release-notes.md;
• rewrites only the links in release-notes-body.md (its content is replaced in step 8).

5. Write the real release notes (en + zh)

Fill rust-srec/docs/{en,zh}/release-notes/vX.Y.Z.md by promoting unreleased.md:

• open with a 1–2 sentence high-level summary, then themed ## sections, each bullet shaped - **Bold lead-in** + a short explanatory paragraph;
• match the tone/structure of the most recent published page (e.g. v0.3.1.md);
• reuse the existing translations in zh/.../unreleased.md verbatim — don't re-translate good prose;
• add a ## Compatibility / ## 兼容性 section only when there's a real migration or behavior note;
• keep en and zh covering the same items in the same order.

6. Reset unreleased

Reset both unreleased.md to the empty shell:

• en — # Release Notes / ## `unreleased` / No staged changes yet for the next release.
• zh — # 更新日志 / ## `unreleased` / 暂无下一个版本的待发布改动。

7. Fix the index placeholders

The script leaves placeholders in both index.md; correct them:

• set the Unreleased bullet to "no changes staged yet" / "暂无下一个版本的待发布改动";
• replace the auto-generated Latest line ("draft release notes…" / "新版本发布说明草稿…") with a real one-line summary;
• delete the extra blank lines the script inserts around the Latest/Archive headings.

8. Fill the GitHub release body

Overwrite rust-srec/docs/release-notes-body.md with the real body: ## rust-srec vX.Y.Z, a summary paragraph, ### Highlights, ### Review before upgrading, then a closing line linking to https://docs.srec.rs/en/release-notes/vX.Y.Z and /zh/release-notes/vX.Y.Z. The release CI reads this file directly for the published GitHub Release body. (The bump script only fixed the links here, so a full rewrite is expected.)

9. Verify

• Every vX.Y.Z link in the sidebars and both index.md resolves to an existing file.
• .vitepress/config.mts still parses (balanced braces/commas around the inserted sidebar entry).
• Confirm the lockfile is --locked-clean: cargo metadata --locked (fast, no compile) — the rust-srec / rust-srec-desktop entries in Cargo.lock must already show the new version, or the tagged release build fails under --locked.
• If docs deps are installed: cd rust-srec/docs && pnpm run docs:build.
• Optional: cargo build --locked -p rust-srec to confirm the version bump compiles under the same flags CI uses.

10. Tag (only when asked)

git tag rust-srec-vX.Y.Z
git push origin rust-srec-vX.Y.Z

Files touched

• Cargo.toml
• Cargo.lock (workspace-member versions, via cargo update --workspace)
• rust-srec/docs/{en,zh}/release-notes/vX.Y.Z.md (new)
• rust-srec/docs/{en,zh}/release-notes/unreleased.md (reset)
• rust-srec/docs/{en,zh}/release-notes/index.md
• rust-srec/docs/.vitepress/config.mts
• rust-srec/docs/release-notes.md
• rust-srec/docs/release-notes-body.md