Release Prep

Release Preparation

Prepare a qsv release by updating version numbers across all required files and generating a changelog entry.

Arguments

• version (required): The new version number (e.g., "16.2.0")
• msrv (optional): New minimum supported Rust version, if changing

Version Bump Checklist

Update the version string in ALL of these files:

1. Cargo.toml (line 3): version = "X.Y.Z"
2. CLAUDE.md: **Current Version**: X.Y.Z in Project Overview
3. .claude/skills/manifest.json: "version" field (MCP server version -- may differ from binary version)
4. .claude/skills/package.json: "version" field (must match manifest.json)
5. CHANGELOG.md: Add new version section at top

If MSRV is changing, also update: 6. Cargo.toml (line 15): rust-version = "X.Y" 7. CLAUDE.md: **MSRV**: Rust X.Y in Project Overview

Changelog Entry

Add a new section at the top of CHANGELOG.md following this format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- (new features)

### Changed
- (changes to existing features)

### Fixed
- (bug fixes)

### Removed
- (removed features)

Use git log from the last release tag to populate the changelog sections. Exclude commits with (mcp) or (plugin) in the title — those belong in the MCP/Plugin changelog (.claude/skills/CHANGELOG.md) and are handled by /mcp-release-prep. Add links to relevant PRs and issues for each changelog entry when possible.

Post-Version-Bump Steps

After version bumps, remind the user to:

1. Run cargo build --locked --bin qsv -F all_features to verify the build (omit --locked if deps changed)
2. Run cargo test -F all_features to verify tests pass
3. Run qsv --update-mcp-skills to regenerate skill JSONs with new version
4. Run bash contrib/completions/generate_examples.bash to regenerate completions
5. Run cargo +nightly fmt to format any changed Rust files
6. Commit all changes together

Important Notes

• The MCP server version in manifest.json/package.json can advance independently of the qsv binary version
• The minimum_qsv_version field in manifest.json tracks the minimum qsv binary needed, NOT the MCP server version
• After bumping Cargo.toml version, omit --locked from cargo commands until Cargo.lock is regenerated

Cross-repo constraints — dathere/qsv-easy-windows-installer

The Windows MSI "Easy installer" is a separate repo that consumes qsv releases directly. Two of its assumptions are things this repo controls, so they are release-time checks:

Installer v1.1.2 (2026-08-09) fixed both of its fragile assumptions — it now reads tag_name instead of the release title, and extracts qsv.exe instead of qsvp.exe.

Verified two different ways, which is worth keeping straight:

• 21.1.0 — the live path. releases/latest returns tag_name: 21.1.0 today, the installer's constructed .../releases/download/21.1.0/qsv-21.1.0-x86_64-pc-windows-msvc.zip returns 200, and qsv.exe is in the archive. This is what a v1.1.2 user gets right now.
• 22.0.1 — the post-promotion target. releases/latest does NOT return it (it is a prerelease), so this was checked by building the same URL from the tag directly: also 200, also contains qsv.exe. It is what releases/latest will return once 22.0.1 is promoted.

What remains:

• Users on Easy installer ≤ v1.1.1 break SILENTLY when the first stable release without qsvp.exe ships — and a release note is the ONLY available remedy. Those versions extract qsvp.exe by hardcoded name. They keep working today only because releases/latest EXCLUDES prereleases, so they still resolve to 21.1.0, which ships qsvp.exe. Promoting 22.0.1 (or any later release) to stable gives them an archive with no qsvp.exe.

  The failure is not a visible error. run_path_update returns () rather than Result, and the frontend calls invoke("run_path_update").finally(...) with no .catch() — so the "Successfully installed qsv" alert fires regardless. Affected users are told it worked while nothing was installed; they will report "qsv is not on my PATH" or "qsv didn't update", never a crash.

  There is no self-update or version-check path in that installer, so it cannot notify already-installed users. The release note is the entire remedy. Word it for the symptom, not an error message they will never see:

  Windows users who installed via the Easy installer: upgrade to v1.1.2 or later before updating qsv, then confirm with qsv --version. Older versions of the installer report success even when the install did not happen.

• Release TITLE == tag is no longer load-bearing for v1.1.2+, but ≤ v1.1.1 still interpolates .name into the download URL as if it were the tag. Keeping titles as the bare version costs nothing and avoids 404ing those users on top of the qsvp failure.

• Check that README's Easy-installer download badge points at the current installer release. The badge is a hardcoded versioned MSI URL (README.md, search qsv-easy-installer_), so it does not follow that repo's releases and goes stale silently. Pointing it at a version the guidance above tells users to upgrade away from is the failure worth avoiding. Current: v1.1.2.