SuperAPI AI Directory

changelog-generator

Coding & development

View repository

Updated 11-15 16:08

About this skill

Changelog Generator

Overview

Turn a git history into a release document. This skill reads Conventional Commits, decides the semantic version bump they imply, and renders a Keep a Changelog entry — the same entry a consumer reads to decide whether upgrading is safe.

The work is mechanical, and that is the point: a changelog generated by rule from structured commits cannot quietly drop a breaking change, and a commit linter that runs before merge is what makes the structure reliable in the first place. Generation and enforcement are two halves of one loop.

When to Use

  • Before publishing a release tag, to write the entry and pick the version
  • In CI, to attach release notes to a GitHub/GitLab release automatically
  • In PR checks, to block commit messages that cannot become release notes
  • In a monorepo, to scope an entry to one package's commits
  • When converting raw git log output into user-facing notes

Do not use this skill to invent prose about a change that has no commit; a changelog entry must trace back to a commit that exists.

Core Capabilities

  • Parse commit messages under Conventional Commit rules, including type(scope)!: and BREAKING CHANGE: footers
  • Detect the semver bump implied by a commit stream (major / minor / patch / none)
  • Group commits into Keep a Changelog sections
  • Render either Markdown for CHANGELOG.md or machine-readable JSON for CI
  • Lint commit messages and exit non-zero on violations

Key Workflows

1. Generate an entry from a git range

python3 scripts/generate_changelog.py --from v1.4.0 --to HEAD

Reads git log in the current repository. Omit --from to use the most recent tag automatically; if there is no tag, the whole history is used.

2. Compute the next version without writing anything

python3 scripts/generate_changelog.py --from v1.4.0 --next --format json

Prints the bump and the resulting version. Use this in a release job to set the tag name before drafting the entry.

3. Generate an entry from a file or stdin

git log --format='%s%n%b%n---COMMIT---' v1.4.0..HEAD \
  | python3 scripts/generate_changelog.py --input - --version 1.5.0

Any input where commits are separated by a blank line and a ---COMMIT--- marker works, so the script never needs to shell out when the caller already has the log.

4. Prepend the entry to CHANGELOG.md

python3 scripts/generate_changelog.py --from v1.4.0 --version 1.5.0 --update CHANGELOG.md

--update prepends under the # Changelog heading and leaves every existing section untouched. It refuses to write a version that is already present.

5. Lint commits before merge

python3 scripts/commit_linter.py --range origin/main..HEAD

Exit code 1 on any violation, with the offending message and the reason. See references/ci-integration.md for wiring this into a pipeline.

Conventional Commit Rules

Format: <type>(<scope>): <description>

Type Meaning Section
feat New capability Added
fix Bug fix Fixed
perf Performance improvement Changed
refactor Restructure, same behavior Changed
docs Documentation only Documentation
test Tests only (omitted by default)
build Build system or dependencies Changed
ci CI configuration (omitted by default)
chore Maintenance (omitted by default)
security Security fix Security
deprecated Marks something for removal Deprecated
remove Removes a capability Removed
revert Reverts a prior commit Changed

Breaking changes are declared one of two ways, and both are honored:

feat(api)!: drop the v1 tasks endpoint
feat(api): drop the v1 tasks endpoint

BREAKING CHANGE: clients must migrate to GET /v2/tasks.

SemVer mapping:

any breaking change  → major
any feat, no breaking → minor
anything else         → patch
no releasable commits → no bump (do not cut a release)

A commit stream containing only chore and test commits produces no entry. Cutting a release for it would tell consumers something changed when, from their side, nothing did.

Commit Quality Standard

A commit message is acceptable when it can become a changelog line without being rewritten by hand:

feat(billing): add proration for mid-cycle plan changes

Not acceptable:

fixed stuff
update code
wip
WIP: almost done

The linter checks structure, not taste. It will pass feat: add thing — it cannot know whether add thing is a good description. That judgment stays with the author and the reviewer. What the linter guarantees is that every merged commit is eligible to be parsed, which is the precondition for generation being trustworthy.

Handling Breaking Changes

Every major bump needs migration guidance. A changelog that says "removed v1 endpoints" without saying what to call instead is a support ticket generator. When a BREAKING CHANGE: footer exists, include it verbatim under the Changed section as a **BREAKING:** bullet — the footer is where authors write the migration path, so it is the one piece of text that must survive generation unedited.

Common Pitfalls

  1. Parsing merge commits as features. Merge pull request #42 from ... is not a Conventional Commit and must be skipped, not coerced into a changelog line. Both scripts ignore messages starting with Merge .
  2. Vague summaries that cannot become release notes. If generation produces "fix: improve things", the failure is upstream in the commit message.
  3. Omitting migration guidance for breaking changes. The ! marker tells you a bump is major; only the footer tells the consumer what to do.
  4. Overwriting historical sections. Prepend, never rewrite. History is append-only, and a changelog that loses old entries is worse than no changelog.
  5. Releasing on non-releasable commits. Chore-only ranges get no bump. Bumping the patch version for internal cleanup trains consumers to ignore version numbers.
  6. Reaching for a tag that does not exist. If --from names an unknown ref, fail loudly rather than silently generating an entry from all of history.

Verification

Before publishing an entry:

  • The version matches the bump the commits imply (breaking → major, feat → minor, else patch)
  • No merge commits or chore noise leaked into the rendered sections
  • Every breaking change has a migration note taken from its footer
  • The date is the release date, not the date of the newest commit
  • Existing changelog sections are intact below the new entry
  • The tag you are about to create matches the version in the heading