| name | bump |
| description | Bump Houndarr version and prepare a release PR. Promotes the Unreleased CHANGELOG block to a versioned block, runs quality gates, opens the PR. Use when the user asks to bump the version, prepare a release, or run /bump. Trigger phrases include bump, release, version bump, prepare release. |
Bump Version and Release
Prepare a release PR following the Houndarr versioning workflow.
Houndarr follows Keep a Changelog 1.1.0: every shipped PR adds a bullet under ## [Unreleased] as part of its own commit, so by the time bump runs, the upcoming release's bullets are already in the file. This skill's job is to promote the Unreleased block to a versioned block, not to draft one from PR titles.
The user's argument is the version bump kind: patch, minor, or an explicit X.Y.Z.
1. Read Current Version
cat VERSION
Note the current version (plain X.Y.Z, no v prefix).
2. Calculate New Version
patch: increment patch (e.g. 1.6.5 → 1.6.6)minor: increment minor, reset patch- Explicit
X.Y.Z: use as-is
Validate the new version is greater than the current one.
3. Verify the Unreleased Block
3a. Refuse to bump an empty Unreleased
awk '/^## \[Unreleased\]$/{found=1; next} found && /^## \[/{exit} found{print}' CHANGELOG.md
If the extracted block contains nothing more than the trailing ---, stop with "## [Unreleased] is empty. Nothing to release." and do not touch VERSION or CHANGELOG.
3b. Verify every bullet's claim before promoting
Mandatory. For every PR referenced in the Unreleased block:
gh pr view N --repo <owner>/<repo> --json title,body
gh pr diff N --repo <owner>/<repo> | head -400
For any bullet that claims behavior (a default, a UI element, an error string, an API response shape), read the relevant source file and pin the claim to a specific file:line. Adopt the PR author's vocabulary for nuance. Every bullet must be defensible with a concrete reference; if you cannot cite one, rewrite or drop the bullet.
3c. Final filter and language pass
Keep only user-facing entries (Added, Changed, Fixed, Removed, Deprecated, Security). Drop CI/refactor/test-only/docs-only/chore/dep-bump-without-impact entries.
If no user-facing entries remain, report "No user-facing changes in Unreleased. Nothing to release." and stop.
Language pass: rewrite bullets that reference internal Python classes / private helpers / src/... paths, exceed 250 chars without a migration reason, use banned phrasings (various / improved / enhanced / better / seamlessly / robustly / significantly / leverages / utilizes / em dashes), or read as past-tense narration. Use markdown [text](url) for links.
4. Present the Promotion Plan for Review
Show the planned CHANGELOG.md unified diff. Wait for approval. Do not proceed without confirmation.
5. Create Branch and Tracking Issue
git fetch origin
git checkout -b chore/bump-X.Y.Z origin/main
gh issue create --title "chore: bump version to X.Y.Z" \
--label "type: chore" --label "priority: medium" \
--body "Release X.Y.Z with <brief summary of user-facing changes>."
6. Update VERSION File
Write the new version (single line, no v prefix).
7. Promote Unreleased in CHANGELOG.md
Rename ## [Unreleased] to ## [X.Y.Z] - YYYY-MM-DD and insert a fresh empty Unreleased block at the top.
8. Run Quality Gates
.venv/bin/python -m ruff check src/ tests/
.venv/bin/python -m ruff format --check src/ tests/
.venv/bin/python -m mypy src/
.venv/bin/python -m bandit -r src/ -c pyproject.toml
9. Commit and Push
git add VERSION CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
git push -u origin HEAD
10. Create PR
gh pr create --title "chore: bump version to X.Y.Z" --body "..."
After merge, remind the user to run git tag vX.Y.Z && git push origin vX.Y.Z to trigger docker.yml, release.yml, and chart.yml.
11. Verify the Tag Push
The tag fires docker.yml and release.yml independently. docker.yml attaches the provenance bundle to the release that release.yml creates, so that upload can fail after the image is already on GHCR. The result is a release that looks complete sitting beside a red workflow run, which is easy to miss.
gh run list --workflow=docker.yml --limit 1
gh release view vX.Y.Z --json assets --jq '.assets[].name'
gh attestation verify oci://ghcr.io/av1155/houndarr:vX.Y.Z --repo av1155/houndarr
Expect a green run, a houndarr-vX.Y.Z.sigstore.json asset on the release, and a verify that reports a matching provenance attestation. If the asset is missing, re-run the failed docker.yml job rather than re-tagging.
