Release

Present the output to the user. For each changed package, show:

• The package name and its new version
• Why it changed (summarize the relevant commits)

Ask the user whether any packages need a minor bump instead of patch. Patch is the default — bump minor for new features, new public API, or breaking changes:

uvr bump --package <package-name> --minor

3. Review

For each changed package, verify its public API against its docs:

1. Read the current public API
2. Check each item on this list:
   • Do the package's docstrings accurately reflect the exported types and internal functionality? Audit natural language descriptions, argument lists, returns notes, code examples, and references.
   • Do all docs (READMEs, docs/, etc) accurately reflect the public API and internal functionality of the package? Audit natural language descriptions, code examples, and references.
3. Fix any discrepancies before continuing

4. Release Notes

For each changed package, write release notes to .uvr/release-notes/<pkg>/<version>.md. This directory is gitignored — notes are ephemeral and consumed at release time.

For each package, review the commits since the baseline. Use the DIFF FROM column from the uvr release --dry-run output — this is the actual tag the planner diffs against, which may differ from the PREVIOUS version (e.g. a -base tag for dev cycles vs a release tag):

git log --oneline <DIFF_FROM_TAG>..HEAD -- packages/<pkg>

Then draft user-facing release notes. Do not dump commit messages — write prose that helps users understand what's new, changed, or fixed. Use markdown.

Present the draft to the user for approval before writing the file. The user may want to adjust wording, add context, or skip notes for certain packages.

Use Keep a Changelog format with a summary blurb at the top. Example:

mkdir -p .uvr/release-notes/my-lib
cat > .uvr/release-notes/my-lib/1.2.0.md << 'EOF'
Dashboard support and stability improvements.

### Added
- New `Widget` class for building dashboards

### Fixed
- Parser no longer crashes on empty input
EOF

Reference the files at release time:

uvr release \
  --release-notes my-lib @.uvr/release-notes/my-lib/1.2.0.md

If no --release-notes flag is provided, the release gets a minimal header only.

5. Dispatch

git add -A
git commit -m "Release v<VERSION>"
git push -u origin "$(git branch --show-current)"
uvr release

When prompted Dispatch release? [y/N], answer y.

If uvr release says dependency pins were updated, commit those first and re-run:

git add -A
git commit -m "chore: update dep pins"
git push
uvr release

6. Monitor

gh run list --workflow=release.yml --limit=1
gh run watch <RUN_ID> --exit-status

If the workflow fails, check which job failed:

gh run view <RUN_ID> --log-failed

If the failure is early (build broke), fix the issue and re-dispatch from scratch:

git add <files>
git commit -m "Fix: <description>"
git push
uvr release

If a later job failed but earlier jobs succeeded, use --skip-to and --reuse-* flags to resume without re-running what already passed. See references/troubleshooting.md#resuming-a-partially-failed-release for the full decision tree.

7. Verify

gh release list --limit 15       # confirm per-package releases exist

If something goes wrong, see references/troubleshooting.md.

8. Merge

ALWAYS merge stable release branches back to main:

git checkout main
git pull --rebase
git merge --no-ff <release-branch> -m "Merge <release-branch>"
git push

After merging, clean up release notes:

rm -rf .uvr/release-notes/

DO NOT merge pre-release branches back to main. Stay on the branch through the alpha → beta → rc → stable cycle, then merge after the stable release. See references/pre-releases.md.

TAKE CARE merging post-release branches back to main — they branch from an old tag, so pyproject.toml versions will conflict. You may need to accept main's versions or cherry-pick just the fix commits. See references/post-releases.md.

Example

User says: "Let's release the new changes"

1. Verify not on main, create a release branch
2. Run uvr release, decline the prompt — shows my-lib is dirty (2 commits: added export, fixed parser)
3. Present to user: "my-lib will bump 0.2.1 -> 0.2.2 (patch). It has a new public export — should this be a minor bump instead?"
4. User says "yes, bump minor" — run uvr bump --package my-lib --minor
5. Review docstrings and docs against current API — new Parser class exported but not documented. Fix docs.
6. Draft release notes: "Added Parser class for structured input handling. Fixed crash on empty input." Present to user for approval.
7. Write approved notes to .uvr/release-notes/my-lib/0.3.0.md
8. Commit, push, run uvr release --release-notes my-lib @.uvr/release-notes/my-lib/0.3.0.md and confirm
9. Monitor workflow, verify GitHub releases
10. Merge release branch back to main, clean up .uvr/release-notes/

References

Commands:

• references/cmd-init.md — scaffold the release workflow
• references/cmd-validate.md — check release.yml against schema
• references/cmd-release.md — plan and dispatch a release (all flags)
• references/cmd-runners.md — manage per-package build runners
• references/cmd-install.md — install from GitHub releases
• references/cmd-skill-init.md — copy Claude skills into project

Guides:

• references/pipeline.md — the three core jobs (build, publish, bump)
• references/release-plan.md — what the release plan JSON contains
• references/custom-jobs.md — how to add your own jobs to the workflow
• references/dev-releases.md — publishing .devN versions for testing
• references/pre-releases.md — alpha, beta, and release candidate versions
• references/post-releases.md — correcting an already-released version
• references/troubleshooting.md — common problems and fixes