Release Notes Generator#

Generate professional release notes following the Keep a Changelog standard.

Input: Previous tag (e.g., v0.0.1)

text

$ARGUMENTS

---

Analyze the changes thoroughly before generating release notes.

Gates#

Do not invent tags, PR numbers, or links. Each row must pass before the work that depends on it.

WhenPass condition (evidence)On failBefore git log / git diff``git tag -l "$PREV_TAG" prints exactly one line matching PREV_TAGStop; report that the tag is missing—do not write changelog entriesBefore categorizinggit rev-parse "$PREV_TAG^{commit}" exits 0Stop; fix PREV_TAG or repo checkoutIf using gh pr listCommand exits 0 and JSON is validFall back to commit subjects + merge-commit URLs only; do not fabricate PR numbersAfter Step 5 footer editsStep 6 footer-gate exits 0 (both grep -q checks pass against the staged CHANGELOG.md)Re-run footer edits from Step 5, then re-run Step 6 until it exits 0

Step 1: Gather Changes#

Run these commands to collect information about changes since the provided tag:

bash

# Store the previous tag
PREV_TAG="$ARGUMENTS"

# Gate: tag must exist (output must be non-empty and match PREV_TAG)
git tag -l "$PREV_TAG"
# If the line above prints nothing, STOP — do not continue below.

# Get the repo URL for PR links
git remote get-url origin

# List commits since last tag
git log ${PREV_TAG}..HEAD --pretty=format:"%h %s" --no-merges

# Get detailed diff stats
git diff ${PREV_TAG}..HEAD --stat

# List changed files by directory
git diff ${PREV_TAG}..HEAD --name-only | sort | uniq

Also gather PR information:

bash

# Get merged PRs since the tag (requires gh CLI)
gh pr list --state merged --search "merged:>=$(git log -1 --format=%ci $PREV_TAG | cut -d' ' -f1)" --json number,title,author,labels

Step 2: Analyze and Categorize#

Categorize each change into exactly one of these groups (in this order):

CategoryIncludeExcludeAddedNew features, new public APIs, new CLI commandsInternal utilities not exposed to usersChangedModified behavior, performance improvements, updated dependencies with user impactRefactors with no behavior changeDeprecatedFeatures marked for future removal-RemovedDeleted features, removed public APIsRemoved internal codeFixedBug fixes, error handling improvementsTest-only fixesSecurityVulnerability patches, security hardening-

Exclude entirely:

• CI/CD configuration changes (unless they affect users)
• Documentation-only changes (unless they reveal new features)
• Code style/formatting changes
• Test-only changes
• Internal refactors with no user-visible impact
• Merge commits

Step 3: Determine Version Number#

Based on the changes, suggest the next version following Semantic Versioning:

• MAJOR (X.0.0): Breaking changes to public API
• MINOR (x.Y.0): New features, backward-compatible
• PATCH (x.y.Z): Bug fixes only

Detect the tag format from existing tags (with or without v prefix).

Step 4: Write Release Notes#

Generate a CHANGELOG.md entry using this exact format:

markdown

## [VERSION] - YYYY-MM-DD

### Added

- **scope:** Add new feature description ([#54](REPO_URL/pull/54))

### Changed

- **Breaking:** Rename `oldName()` to `newName()` for consistency ([#145](REPO_URL/pull/145))

  **Migration:** Replace all calls to `oldName()` with `newName()`.

### Deprecated

- **scope:** Deprecate `legacy_function()` in favor of `new_function()` ([#143](REPO_URL/pull/143))

### Removed

- **Breaking:** Remove deprecated `old_function()` ([#141](REPO_URL/pull/141))

### Fixed

- **scope:** Fix race condition when multiple workers access shared state ([#139](REPO_URL/pull/139))

### Security

- **deps:** Update vulnerable package to patched version ([#49](REPO_URL/pull/49))

Writing Rules#

Format requirements:

• Start every entry with an imperative verb: Add, Fix, Remove, Update, Improve, Rename, Deprecate, Patch
• Include scope prefix in bold when present: **server:**, **cli:**, **api:**
• One line per change (except breaking changes which get migration notes)
• Include PR/issue link at end of line
• Sort entries within each category by importance (most impactful first)
• Omit empty categories entirely

Breaking changes:

• Prefix with bold **Breaking:**
• List first within their category
• Add a **Migration:** block on the next line explaining exactly what users must change
• Include before/after code examples for API signature changes

Tone:

• Write for library consumers, not maintainers
• Focus on what changed for users, not how it was implemented
• Be specific—never write "various improvements" or "bug fixes"
• Each entry should be understandable without reading the PR

Bad examples to avoid:

markdown

# BAD - Too vague
- Fixed bugs
- Performance improvements
- Updated dependencies

# BAD - Implementation-focused
- Refactored the internal state machine to use async/await

# BAD - Missing context
- Fixed #234

Good examples to follow:

markdown

# GOOD - Specific and user-focused
- **server:** Fix timeout errors when processing files larger than 100MB ([#234](URL))
- **cli:** Add `--dry-run` flag to preview changes before execution ([#235](URL))
- **api:** Improve cold-start latency from 2.3s to 0.8s by lazy-loading plugins ([#236](URL))

Step 5: Update CHANGELOG.md#

1. If CHANGELOG.md exists:
   • Insert new version after the ## [Unreleased] section (or at top if no Unreleased)
2. If CHANGELOG.md doesn't exist, create it with this header:

markdown

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

1. Update the footer reference links at the bottom of the file. This step is mandatory — CodeRabbit and other reviewers will flag the changelog as incomplete if these are missing. Two edits are required:

   a. Advance [Unreleased] so it compares against the new version instead of the previous one. b. Insert a new [NEW_VERSION] line right below [Unreleased], comparing the previous tag to the new one.

   Example diff (releasing 3.2.0 after 3.1.0): diff

   -[Unreleased]: https://github.com/OWNER/REPO/compare/v3.1.0...HEAD
   +[Unreleased]: https://github.com/OWNER/REPO/compare/v3.2.0...HEAD
   +[3.2.0]: https://github.com/OWNER/REPO/compare/v3.1.0...v3.2.0
    [3.1.0]: https://github.com/OWNER/REPO/compare/v3.0.0...v3.1.0
   
   

   After editing, run Step 6 to verify both footer lines exist and are correct. Do not skip Step 6 — it is the hard gate that prevents the recurring "missing footer compare link" reviewer feedback.

Step 6: Verify CHANGELOG footer compare links (HARD GATE)#

This is the enforcement gate for footer compare links. It must run before gen-release-notes reports success and before any commit step in the release workflow. It is not advisory — both grep -q checks must exit 0 or the gate fails with a named missing line.

Run this block exactly:

bash

# Read the staged CHANGELOG.md blob (index), not the working tree, so unstaged
# edits cannot make the gate pass when the commit would actually fail.
STAGED_CHANGELOG=$(git show :CHANGELOG.md)

# Extract NEW and PREV versions from the staged CHANGELOG.md.
# We only match numeric `## [X.Y.Z]` headings so `## [Unreleased]` is skipped.
NEW_VERSION=$(printf '%s\n' "$STAGED_CHANGELOG" | grep -m1 -E '^## \[[0-9]+\.[0-9]+\.[0-9]+\]' | sed -E 's/^## \[([0-9]+\.[0-9]+\.[0-9]+)\].*/\1/')
PREV_VERSION=$(printf '%s\n' "$STAGED_CHANGELOG" | grep -m2 -E '^## \[[0-9]+\.[0-9]+\.[0-9]+\]' | sed -n '2p' | sed -E 's/^## \[([0-9]+\.[0-9]+\.[0-9]+)\].*/\1/')

if [ -z "$NEW_VERSION" ] || [ -z "$PREV_VERSION" ]; then
  echo "GATE FAIL: could not extract NEW_VERSION ($NEW_VERSION) or PREV_VERSION ($PREV_VERSION) from staged CHANGELOG.md"
  exit 1
fi

# Infer optional tag prefix (`v` or empty) from the existing [Unreleased] footer.
# Step 3 explicitly allows tags with or without `v`; never hardcode `v` here.
# Fall back to `v` only when no [Unreleased] footer exists yet (first release).
TAG_PREFIX=$(printf '%s\n' "$STAGED_CHANGELOG" | sed -nE 's|^\[Unreleased\]: .*/compare/(v?)[0-9]+\.[0-9]+\.[0-9]+\.\.\.HEAD$|\1|p' | head -1)
if ! printf '%s\n' "$STAGED_CHANGELOG" | grep -qE '^\[Unreleased\]:'; then
  TAG_PREFIX="v"
fi

echo "Gating footer compare links: NEW=${TAG_PREFIX}${NEW_VERSION}, PREV=${TAG_PREFIX}${PREV_VERSION}"

# Escape dots so they match literally inside the regex.
NEW_RE=${NEW_VERSION//./\\.}
PREV_RE=${PREV_VERSION//./\\.}

# Check 1: the new [NEW_VERSION] footer line exists and points PREV->NEW.
printf '%s\n' "$STAGED_CHANGELOG" | grep -qE "^\[${NEW_RE}\]: .*compare/${TAG_PREFIX}${PREV_RE}\.\.\.${TAG_PREFIX}${NEW_RE}\$" \
  || { echo "GATE FAIL: missing footer line: [${NEW_VERSION}]: .../compare/${TAG_PREFIX}${PREV_VERSION}...${TAG_PREFIX}${NEW_VERSION}"; exit 1; }

# Check 2: the [Unreleased] footer line is advanced to compare from the new tag.
printf '%s\n' "$STAGED_CHANGELOG" | grep -qE "^\[Unreleased\]: .*compare/${TAG_PREFIX}${NEW_RE}\.\.\.HEAD\$" \
  || { echo "GATE FAIL: [Unreleased] is not advanced; expected: [Unreleased]: .../compare/${TAG_PREFIX}${NEW_VERSION}...HEAD"; exit 1; }

echo "Footer compare links verified: [${NEW_VERSION}] and [Unreleased] both present and correct."

Pass condition (objective): both grep -q invocations above exit 0 against the staged CHANGELOG.md. The block must print Footer compare links verified: ... and exit 0.

On fail: the gate names the missing or wrong line. Return to Step 5 and edit CHANGELOG.md to add or correct that line, then re-run this block. Do not proceed to Step 7 or report success until the block exits 0.

Step 7: Output Summary#

After updating the changelog, provide:

1. The suggested version number with rationale
2. Summary of categorized changes
3. Any breaking changes that need special attention
4. Confirmation that CHANGELOG.md was updated

Conventional Commits Mapping#

Map commit prefixes to changelog categories:

Commit PrefixChangelog Categoryfeat(scope):Addedfeat!(scope):Added (with Breaking prefix)fix(scope):Fixedperf(scope):Changedsecurity(scope):Securitydocs:, chore:, ci:, test:, style:Exclude