Release Version

Skill: Release Version

Use this skill to turn merged PR history into a release decision and, when warranted, an annotated Git tag. It is intentionally conservative: tag only after reviewing the PRs since the previous tag and confirming the target revision is current and releasable.

Workflow

1. Synchronize release refs first.

   git fetch origin main --tags --prune

   Use origin/main as the release target unless the user explicitly names another ref. The current worktree may be dirty; do not tag the local HEAD unless it is the requested release target.

2. Collect the release context.

   .agents/skills/release-version/scripts/release_context.py --fetch --ref origin/main

   The script reports the latest reachable tag, merged PRs/commits since that tag, a deterministic impact classification, and a suggested next tag. Treat this as evidence collection, not as the final decision.

3. Review every PR since the last tag. For each PR reported by the script, inspect at least the title, body, file list, and release-relevant diff:

   gh pr view <n> --json number,title,body,labels,mergedAt,files,url
   gh pr diff <n>

   Focus on user-visible behavior, protocol behavior, security, configuration, database/schema changes, dependency/runtime changes, docs-site/public documentation changes, and operational risk. Ignore purely internal agent metadata unless it changes shipped behavior.

4. Decide release need.

   • No tag: no PRs since the last tag, or only tests/CI/internal docs/agent-only cleanup with no shipped behavior.
   • Patch: bug fixes, security hardening without incompatible behavior, dependency updates, metrics/logging correctness, docs corrections for a published release, or low-risk operational fixes.
   • Minor: new user-visible features, new protocol/vendor support, new config/API surface, new automation that affects operators, or meaningful docs/product capability expansion.
   • Major: breaking API/config/protocol behavior, incompatible data migration, removed feature, changed deployment contract, or explicit BREAKING CHANGE. When in doubt between no tag and patch, prefer no tag unless a real consumer/operator would benefit from a release artifact.

5. Check release gates before tagging.

   • git rev-parse origin/main is the intended target SHA.
   • The proposed tag does not already exist locally or remotely.
   • Open release-blocking PRs/issues are understood. At minimum, list open PRs:

     gh pr list --state open --json number,title,headRefName,labels,url

   • CI for the target SHA is green or explicitly accepted by the user:

     gh run list --branch main --limit 10 --json databaseId,headSha,status,conclusion,workflowName,event

   • v* tags also trigger .github/workflows/docker-publish.yml. Confirm Docker Hub credentials (DOCKERHUB_USERNAME / DOCKERHUB_TOKEN) are configured and writable. For GHCR, confirm the talkincode/toughradius package inherits this repository's Actions access, or that PKG_GITHUB_TOKEN has write:packages (PKG_GITHUB_USERNAME is optional when the token owner differs from the tag actor). The Docker workflow treats Docker Hub as required, probes GHCR write access before building, skips the GHCR push when the probe is denied, and reports the result in the run summary; fix package access and rerun the tag workflow rather than creating a duplicate tag for the same source.
   • If the repository has release notes, changelog, packaging, or version-file conventions, update them in a PR first. This skill only creates a tag directly when no source-file change is required.

6. Create the tag only when release is warranted. Use an annotated tag at the exact target SHA:

   target=$(git rev-parse origin/main)
   git tag -a <new-tag> "$target" -m "$(cat /tmp/toughradius-release-notes.txt)"
   git push origin <new-tag>

   The tag message should include: previous tag, target SHA, release impact, reviewed PR numbers, and a concise release summary. Do not create a GitHub Release unless the user asks for one.

7. Report the outcome. If tagged, report the tag, target SHA, previous tag, release type, and PR summary. If not tagged, report the last tag, reviewed PRs/commits, and the concrete reason no release is needed.