Changelog

Changelog

Every invocation creates a versioned release. Gathers commits since the last tag, writes a dated release entry in CHANGELOG.md, commits, tags, and pushes. Follows Keep a Changelog format and Conventional Commits conventions.

Step 1: Pre-Flight Checks

1. git status --porcelain must return empty (CHANGELOG.md exempt). If dirty, abort and tell the user to commit or stash first.
2. git fetch origin
3. Branch not behind remote: git rev-list --count HEAD..origin/$(git branch --show-current). If behind, abort and tell the user to pull first.

Step 2: Determine Version

If $ARGUMENTS contains a version (e.g., v1.2.0), use it directly.

Otherwise, auto-detect from commits since the last tag:

git tag --sort=-v:refname | head -1

If no tags exist, treat the current version as 0.0.0.

Scan commits: git log --pretty=format:"%s%n%b" <last-tag>..HEAD. Apply the highest-priority rule:

If all commits were filtered (docs, test, ci, chore only), report "No release needed" and stop.

Report the detected version before continuing:

Next version: X.Y.Z (bump — reason)
Commits since vCURRENT: N total (N included, N filtered)

Step 3: Check No Duplicate Tag

git tag -l vX.Y.Z. If the tag already exists, abort and report the conflict.

Step 4: Gather and Categorize Commits

1. Get all commits since the last tag: git log --oneline <last-tag>..HEAD
2. Categorize using the mapping below.
3. Filter noise: always drop merge commits, ci:, chore:, test:, docs:, and style: commits. For refactor: commits, include only when the diff touches a public API, CLI flag, configuration schema, or user-facing output; otherwise drop.
4. Translate technical commits to user-friendly descriptions.

Step 5: Write Release Entry

1. If no CHANGELOG.md exists, create one with a header and footer links (detect remote URL with git remote get-url origin).
2. If CHANGELOG.md exists, read it and preserve all existing content.
3. Add a new versioned section ## [X.Y.Z] - YYYY-MM-DD with today's date, placed above existing version sections.
4. Remove any existing Unreleased section and its footer link.
5. Update footer comparison links.
6. Verify: Entry count matches categorized commit count (minus filtered).

Step 6: Commit, Tag, Push

1. git add CHANGELOG.md
2. git commit -m "Release vX.Y.Z"
3. git tag -a vX.Y.Z -m "Release vX.Y.Z - <one-line summary of changes>"
4. git push --follow-tags
5. Verify: git ls-remote --tags origin | grep vX.Y.Z and report the version, tag, and commit hash.

Commit Categorization

Map Conventional Commits prefixes to Keep a Changelog sections. See references/changelog_format.md for the full mapping, writing style, and anti-patterns.

Always include: features, user-facing bug fixes, breaking changes, security fixes. Always filter: merge commits, internal refactors, test changes, CI config, typos.

Translate technical commits to user-friendly language:

• fix(auth): resolve JWT expiry edge case -> "Fixed session timeout issues for long-running sessions"
• feat(api): add /users endpoint -> "Added user management API endpoints"

Git Analysis Commands

# All commits since last tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD

# Commits between tags
git log --oneline v1.0.0..v1.1.0

# Current tags
git tag --sort=-v:refname | head -10

Output Format

# Changelog

All notable changes to this project will be documented in this file.

## [1.1.0] - 2026-02-13

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

## [1.0.0] - 2026-02-01

### Added
- Initial release features

[1.1.0]: https://github.com/owner/repo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/owner/repo/releases/tag/v1.0.0

Examples

References