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.