release-version

Release Version

Goal

Release the current project according to its own conventions. First infer and summarize the repository's release process, then update version metadata and release notes, create the release commit and tag, push the commit and tag, verify GitHub Actions, update the GitHub Release description with this release's changelog content, and update the repository owner's Homebrew tap when present so Homebrew installs the new version.

Safety Rules

• Treat release work as high impact. Do not publish, push, tag, or edit a GitHub Release until the intended version, branch, remote, and release flow are clear.
• Prefer the repository's documented release process over this generic workflow.
• Do not overwrite existing tags or releases unless the user explicitly asks and the risk is understood.
• Do not force-push release branches or tags.
• Stop and ask if the version number, release branch, package registry, or release target is ambiguous.
• Keep unrelated working-tree changes out of the release commit.
• Treat a Homebrew tap update as part of the release when the repository exists. Do not report the release as fully complete until the tap is updated and verified, or a concrete blocker is reported.
• Do not guess release asset URLs, Formula/Cask names, archive formats, platform mappings, or checksums. Derive them from the published release and the existing tap definition.
• Do not update a tap before the GitHub Release and required assets are available. Never commit placeholder or stale checksums.
• Keep unrelated changes in the tap worktree out of the tap update commit.

Workflow

1. Determine repository and release target:
   • Run git rev-parse --show-toplevel, git status --short, git branch --show-current, and git remote -v.
   • Identify the intended release version from the user's request, existing version files, tags, or project docs.
   • Confirm the working tree contains only intended release changes or isolate unrelated changes.
2. Discover the project release process:
   • Read files such as README*, CONTRIBUTING*, RELEASE*, CHANGELOG*, package manager manifests, CI configs, .github/workflows/*, Makefiles, scripts, and project docs.
   • Search for release scripts and version commands in package.json, pyproject.toml, Cargo.toml, go.mod, Gradle/Maven files, Makefiles, shell scripts, and CI workflows.
   • Inspect recent release commits and tags with git tag --sort=-creatordate, git log --decorate --oneline, and git show <recent-release-tag> when useful.
   • Summarize the inferred release flow before executing irreversible operations.
3. Choose the version bump:
   • Follow the user's requested version when provided.
   • Otherwise infer the next SemVer version from changelog content, Conventional Commits, or repository policy.
   • Check whether the tag format is vX.Y.Z, X.Y.Z, package-specific, or project-specific.
4. Update version metadata:
   • Modify every authoritative version location required by the project, such as package manifests, lockfiles, language-specific metadata, docs, CLI constants, or generated version files.
   • Use the repository's versioning command when available, such as npm version --no-git-tag-version, poetry version, cargo set-version, Maven/Gradle release tasks, or project scripts.
   • Inspect resulting diffs to ensure only intended version changes were made.
5. Update changelog and release notes:
   • Generate or update changelog content for the release using the repository's changelog format.
   • If an update-changelog skill is available and the user request requires changelog generation, use it for the changelog step.
   • Ensure the GitHub Release notes include this release's changelog content, not just an empty tag or autogenerated placeholder.
   • Preserve existing Chinese, English, or bilingual release-note style when present.
6. Verify before publishing:
   • Run the project's release-required tests, type checks, builds, changelog checks, and packaging checks discovered from docs or CI.
   • If the repository has unit tests, run the relevant or full suite required for release.
   • If the repository has release, packaging, or smoke-test commands, run them before tagging.
   • Do not create the tag until local verification passes or the user explicitly accepts the skipped checks.
7. Commit release changes:
   • Stage only release-related files.
   • Use a Conventional Commits message such as chore(release): prepare vX.Y.Z.
   • Inspect git diff --cached before committing.
8. Create the tag:
   • Use the repository's existing tag style.
   • Prefer an annotated tag for release tags unless the repository convention uses lightweight tags.
   • Include a concise tag message such as Release vX.Y.Z.
   • Verify the tag points to the intended release commit.
9. Push commit and tag:
   • Push the release branch to the correct remote.
   • Push the new tag explicitly.
   • Verify the remote branch and tag exist after push.
10. Check GitHub Actions:

• Use gh run list, gh run watch, gh run view, or the repository's GitHub Actions page to find workflows triggered by the release commit or tag.
• Wait for relevant release/build workflows to finish when practical.
• If a workflow fails, inspect logs, summarize the failure, and fix it when in scope before re-running or re-pushing.

1. Create or update the GitHub Release:

• Use the repository's normal release automation when available.
• Otherwise use gh release create or gh release edit for the new tag.
• Put the changelog content for this version into the release notes.
• Mark prereleases or drafts according to the version and project convention.
• Verify the final GitHub Release URL and notes.

1. Discover and update the Homebrew tap:

• After the GitHub Release and its required assets are published, use gh repo view --json owner,nameWithOwner to determine the source repository owner.
• Check for <owner>/homebrew-tap with gh repo view <owner>/homebrew-tap. Also inspect the source repository's release workflows, documentation, and scripts for an explicitly configured tap repository; use that repository when it differs from the owner default.
• If no tap repository exists and none is configured, record that Homebrew maintenance was skipped because there is no tap. Do not create a new tap unless the user explicitly requests it.
• If the tap exists, inspect its README*, .github/workflows/*, Formula/, Casks/, scripts, recent commits, and contribution instructions before editing. Determine whether source-repository automation is expected to update the tap.
• If release automation updates the tap, wait for it to finish and verify the resulting Formula/Cask. Make a manual update only when automation is absent, failed, or did not produce the correct version.
• Clone or reuse a clean tap worktree without disturbing unrelated local changes. Locate the Formula or Cask associated with the released project from existing names, URLs, descriptions, and tap documentation; do not assume it matches the source repository name.
• Update every version-dependent field required by the existing definition, including version, release asset or source URLs, platform/architecture mappings, and SHA-256 checksums. Preserve the tap's existing Ruby style and installation strategy.
• Obtain URLs and assets from the published GitHub Release. Download each referenced artifact and compute its checksum locally with sha256sum or shasum -a 256; do not copy an unverified checksum from logs or use a checksum for a redirect/error response.
• Inspect the tap diff and ensure it changes only files required for this release. Run the tap's documented checks plus applicable Homebrew checks such as brew style, brew audit --strict, or brew audit --cask for the changed definition.
• Commit the tap update using its established convention, otherwise use chore: update <formula-or-cask> to <version>. Push to the tap's normal default branch without force-pushing.
• Derive the Homebrew tap name from the selected repository (<tap-owner>/homebrew-<tap-name> becomes <tap-owner>/<tap-name>). Verify the pushed definition through GitHub, then refresh it locally with brew update or brew tap --force-auto-update <tap-owner>/<tap-name>.
• Prove the public installation path resolves to the new release. Run the documented brew install or brew upgrade command when it is safe in the current environment, followed by the installed command's version check. At minimum, use brew info and brew fetch to verify the published definition and artifacts when installation would be destructive or unsupported.
• Confirm the reported or installed version equals the released version. Treat stale tap metadata, checksum mismatches, unavailable assets, failed tap CI, or an older installed version as release blockers to investigate and fix when in scope.