git-release · v1.2.0 · 2026-09-25 · sha256 8decc154815d158e
git-release v1.2.0A
Immutable. This exact content never changes and is served at /api/v1/blob/8decc154815d158e.
--- name: git-release description: Create semantic version releases with automated changelog generation from conventional commits, version file bumps (package.json, pyproject.toml, Cargo.toml, etc.), git tagging, and GitHub release publishing, for repos on a simple main-branch workflow (no release/hotfix branches). Use when users want to create a release, tag a version, generate a changelog, bump version numbers, cut a release, or publish a GitHub release. Not for release/hotfix branch topology or promoting one branch to another (use gitflow). Not for everyday conventional commit messages (use git-commit, this skill only creates the single release commit itself). metadata: summary: "Semantic version releases with automated changelog generation" author: mgiovani version: 1.2.0 --- # Release Manager Create semantic version releases with automated changelog generation from conventional commits, version file updates, and GitHub release publishing. ## Quality Guidelines Release operations are high-consequence and irreversible once pushed: 1. Verify every change: analyze actual commits, not assumptions 2. Confirm version bump: the detected semver bump must match the change scope 3. Validate changelog: every entry must correspond to a real commit 4. User approval required: confirm before executing anything in Phase 5 ## Workflow ### Phase 1: Collect Commits Since Last Tag 1. Find the latest tag: ```bash git describe --tags --abbrev=0 2>/dev/null || echo "none" ``` - If no tags exist, collect all commits on the current branch - If a tag exists, collect commits since that tag 2. Collect commits: ```bash # With existing tag git log <last-tag>..HEAD --format="%H %s" --no-merges # Without existing tag (first release) git log --format="%H %s" --no-merges ``` 3. Validate preconditions: - Working tree is clean: `git status --porcelain` - On the expected branch (main/master or release branch) - Remote is up to date: `git fetch origin && git log HEAD..origin/$(git branch --show-current) --oneline` - If there are no commits since the last tag, abort with a clear message ### Phase 2: Auto-detect version bump 1. Parse each commit using conventional commit format: - Extract type: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` - Extract scope (optional): text in parentheses after type - Detect breaking changes: `!` after type/scope OR `BREAKING CHANGE:` in commit body - For non-conventional commits, classify as `other` This is plain regex/string parsing over commit subjects, do it inline regardless of commit count, no agent needed. 2. Determine version bump: load `references/semver-guide.md` for the full commit-type → bump mapping and pre-1.0 rules. The highest-priority bump wins (major > minor > patch). 3. Calculate new version: - Parse last tag as semver (strip leading `v` if present) - If no previous tag, start from `0.1.0` (first feature release) or `1.0.0` if user specifies - Apply the detected bump - Respect `--major`, `--minor`, or `--patch` override from arguments 4. Display version summary: the counts must reflect commits you actually parsed in step 1, never estimated: ``` Current version: v1.2.3 Detected bump: minor (2 features, 5 fixes, 3 chores) New version: v1.3.0 Breaking changes: none ``` ### Phase 3: Build the CHANGELOG Entry 1. Read existing CHANGELOG.md (if it exists) to understand the current format and preserve it 2. Group commits by type using this order and heading format: ```markdown ## [1.3.0](https://github.com/owner/repo/compare/v1.2.3...v1.3.0) (YYYY-MM-DD) ### Breaking Changes - **scope:** description ([hash](url)) ### Features - **scope:** description ([hash](url)) ### Bug Fixes - **scope:** description ([hash](url)) ### Performance - **scope:** description ([hash](url)) ### Documentation - **scope:** description ([hash](url)) ### Other Changes - **scope:** description ([hash](url)) ``` Type-to-heading mapping: - Breaking changes (any type with `!` or `BREAKING CHANGE:`) → Breaking Changes - `feat` → Features - `fix` → Bug Fixes - `perf` → Performance - `docs` → Documentation - `refactor`, `style`, `test`, `build`, `ci`, `chore`, `revert`, `other` → Other Changes Only include sections that have entries. Omit empty sections. 3. Generate comparison URL: ```bash gh repo view --json url -q .url 2>/dev/null || git remote get-url origin ``` 4. Construct the changelog entry: - Use short commit hashes (7 chars) linked to the full commit URL - If scope exists, bold it: `**scope:** description` - If no scope: just the description - Date format: `YYYY-MM-DD` 5. Insertion logic (defines the mechanics only, nothing is written to disk yet, so the Phase 4 preview and a later abort both stay side-effect-free): - If CHANGELOG.md exists, insert the entry after the `# Changelog` header, preserving existing entries below it - If CHANGELOG.md does not exist, this entry becomes the file's first entry under a new `# Changelog` header - Maintain a blank line between the header and first entry, and between entries - The actual file write happens in Phase 5 step 2, or Phase 3b step 2 for changelog-only mode: both reuse this same logic 6. Verify the write (same call sites as step 5): after writing the file, re-read it and confirm the new version heading (`## [<new-version>]`) is present and that at least one section under it has a real bullet line, not just an empty `### Heading` with nothing below. A narrated changelog is not evidence the write succeeded, check the file on disk, e.g.: ```bash grep -A2 "## \[<new-version>\]" CHANGELOG.md ``` If the heading is missing, or every section under it is empty, abort before creating the release commit: "CHANGELOG.md write produced empty sections, release aborted, no commit created." Do not proceed to Phase 5 step 3 (or, in changelog-only mode, report success) on a failed verification. ### Phase 3b: Changelog-only mode (if `--changelog-only`) When `--changelog-only` is passed, skip Phases 4-6 entirely: 1. Run Phases 1-3 normally (collect commits, detect version bump, build the changelog entry) 2. Write CHANGELOG.md using the Phase 3 step 5 insertion logic, including its step 6 verification (abort here on a failed verification, do not report success) 3. Display the updated changelog entry to the user 4. Stop here: no tag, version bump, commit, or GitHub release Use case: draft a changelog before deciding on a release, or maintain a running changelog during development. ```bash # Example output for --changelog-only git-release --changelog-only # → Scans commits since v1.2.3 # → Writes changelog entry to CHANGELOG.md # → Reports: "CHANGELOG.md updated with 8 commits. No tag or release created." ``` ### Phase 4: User Approval 1. Display release summary: ``` === Release Summary === Version: v1.2.3 → v1.3.0 (minor) Tag: v1.3.0 Commits: 12 commits since v1.2.3 Branch: main Changelog preview: ───────────────────── ## [1.3.0](...) (2025-01-15) ### Features - **auth:** add OAuth2 login support (abc1234) - **api:** add rate limiting endpoint (def5678) ### Bug Fixes - **api:** resolve null pointer in user endpoint (ghi9012) ───────────────────── Version files to update: - package.json (1.2.3 → 1.3.0) - pyproject.toml (1.2.3 → 1.3.0) Actions: 1. Update version files 2. Update CHANGELOG.md 3. Create git commit: "chore(release): v1.3.0" 4. Create git tag: v1.3.0 5. Push commit and tag to origin 6. Create GitHub release with changelog ``` 2. If `--dry-run` (or `-n`) was passed: stop here. The summary above already shows everything that would happen, this flag is the only dry-run entry point, so no separate "preview" option is offered below. 3. Otherwise, ask for confirmation: - "Proceed with release": continue to Phase 5 - "Change version": ask for the desired version, recalculate, re-display the summary - "Abort": exit cleanly with "Release cancelled." ### Phase 5: Execute Release Execute all release actions in strict order. Stop immediately if any step fails and report which step failed and what manual cleanup may be needed. 1. Update version files (detect and update all that exist): - `package.json`: Update `"version": "x.y.z"` field - `package-lock.json`: Update `"version": "x.y.z"` at root level - `pyproject.toml`: Update `version = "x.y.z"` under `[project]` or `[tool.poetry]` - `Cargo.toml`: Update `version = "x.y.z"` under `[package]` - `VERSION` or `VERSION.txt`: Replace entire file content - `setup.cfg`: Update `version = x.y.z` under `[metadata]` - `build.gradle` / `build.gradle.kts`: Update `version = "x.y.z"` - Other version files: Skip unknown formats, notify user 2. Write CHANGELOG.md using the Phase 3 step 5 insertion logic, including its step 6 verification (abort before step 3 below if verification fails). 3. Create release commit: ```bash git add -A git commit -m "chore(release): v<new-version>" ``` 4. Create annotated tag: ```bash git tag -a v<new-version> -m "Release v<new-version>" ``` 5. Push commit and tag: ```bash git push origin $(git branch --show-current) git push origin v<new-version> ``` 6. Create GitHub release (unless `--no-github` flag is set): ```bash notes_file=$(mktemp -t release-notes) # write the changelog entry (without the "## [version]" header) to $notes_file gh release create v<new-version> \ --title "v<new-version>" \ --notes-file "$notes_file" \ --latest rm -f "$notes_file" ``` A fixed path (e.g. `/tmp/release-notes.md`) can collide across concurrent or repeated runs: `mktemp` guarantees a unique file. 7. Display completion summary: ``` Release v1.3.0 completed successfully! - Commit: abc1234 chore(release): v1.3.0 - Tag: v1.3.0 - GitHub: https://github.com/owner/repo/releases/tag/v1.3.0 - Changelog: Updated CHANGELOG.md ``` ## Argument Parsing Parse optional arguments from `command arguments`: - `--major`: Force a major version bump (overrides auto-detection) - `--minor`: Force a minor version bump (overrides auto-detection) - `--patch`: Force a patch version bump (overrides auto-detection) - `--dry-run` or `-n`: Show what would happen without making changes (see Phase 4 step 2, the single dry-run entry point) - `--no-github`: Skip GitHub release creation (only local tag + changelog) - `--changelog-only`: Generate/update CHANGELOG.md only, skip tagging, version bumps, and GitHub release When force flags conflict (e.g., `--major --minor`), use the highest: major > minor > patch. ## Edge Cases - No conventional commits: If commits don't follow conventional format, default to `patch` bump and list all commits under Other Changes - Pre-release versions (e.g., `0.x.y`): Follow semver pre-1.0 rules, breaking changes bump minor, features bump minor, fixes bump patch - Monorepo: If multiple `package.json` files exist, only update the root one. Warn the user about other version files found - Dirty working tree: Abort with a clear message asking the user to commit or stash changes first - No remote: If `git push` fails due to no remote, skip push and GitHub release, warn the user - Tag already exists: If the computed tag already exists, abort and suggest a force flag or a different version - CHANGELOG write verification fails: If the re-read in Phase 3 step 6 shows a missing heading or empty sections, abort before the release commit, never commit a changelog write you haven't confirmed on disk ## Important Notes - Conventional Commits: Works best with conventional commits (see the git-commit skill) - Tag Format: Always uses `v` prefix (e.g., `v1.3.0`) unless existing tags use a different convention - CHANGELOG Format: Follows [Keep a Changelog](https://keepachangelog.com/) conventions - Semver: Follows [Semantic Versioning 2.0.0](https://semver.org/) - Never skip hooks: Never pass `--no-verify` on the release commit - No inline execution: Nothing in Phase 1-4 writes to the working tree, the first mutation is Phase 5 step 1, after approval ## Examples ```bash # Auto-detect version bump from commits git-release # Force a major version bump git-release --major # Preview without making changes git-release --dry-run # Release without creating a GitHub release git-release --no-github # Force minor bump, dry run git-release --minor --dry-run # Update CHANGELOG.md only (no tag or release) git-release --changelog-only ```