changelog

Produce a changelog from what actually shipped: the commits, merged PRs, and references between two points in history. Write it for the people who read releases (users, integrators), not as a raw git log dump.

Hard rules: never break these

• Base it on real history, never invent. Every entry must trace to a commit, PR, or issue. No speculative or aspirational items.
• Match the existing format. If CHANGELOG.md or a changelog tool already exists, follow its structure, headings, and conventions exactly. Don't impose a new style on an established file.
• Never rewrite already-released sections. Add the new version on top; leave shipped entries untouched.
• Write for humans. Translate commits into user-facing outcomes. Drop pure-noise commits (formatting, CI tweaks, internal refactors) unless they affect users.
• Surface breaking changes prominently. They're the entries most likely to ruin someone's day if missed.

Step 1: Determine the range

• Last release to now: git describe --tags --abbrev=0 gives the latest tag; the range is <lastTag>..HEAD.
• Between two releases: <olderTag>..<newerTag>.
• First release ever: use the full history (no lower bound).
• Honor an explicit range or version the user passed.

Step 2: Gather the raw material

• Commits in range: git log <range> --no-merges --pretty=format:'%H %s' (and %b for bodies, to catch BREAKING CHANGE: footers).
• Merge commits / PR numbers: git log <range> --merges and (#123) references in subjects.
• Parse Conventional Commit prefixes (feat, fix, perf, refactor, docs, etc.), scopes, the ! breaking marker, and issue/ticket references (#123, JIRA-456, CU-abc).
• Capture authors if the project credits contributors.

Step 3: Detect the project's convention

Look before you write; adopt what's already in use:

• An existing CHANGELOG.md / CHANGES/HISTORY file → mirror its format (most follow Keep a Changelog).
• Tooling config that owns the changelog, e.g. conventional-changelog/standard-version, release-please, changesets (.changeset/), git-cliff (cliff.toml), towncrier (newsfragments/), auto, semantic-release. If one is configured, prefer driving it over hand-writing, and explain how to run it.

Step 4: Categorize

Default to Keep a Changelog sections, mapping Conventional Commits onto them:

List Breaking changes in their own prominent block (from ! markers and BREAKING CHANGE: footers), with the migration path. Omit chore, ci, build, style, and test unless user-visible.

Step 5: Write the entries

• One concise, imperative, user-facing line per change: describe the outcome, not the diff.
• Link references: ... (#123), ticket IDs, or commit short-SHAs per the project's style.
• Deduplicate (squash-merge plus follow-up commits often describe the same change) and merge related items.
• Order sections by reader impact: Breaking → Added → Changed → Fixed → the rest.

Step 6: Assemble and place

• Head the section with the version and ISO date: ## [1.4.0] - 2025-06-06. Use ## [Unreleased] if the version isn't cut yet.
• Prepend under any existing [Unreleased]/top of file; never disturb prior releases.
• Maintain comparison links at the bottom if the file uses them ([1.4.0]: https://…/compare/v1.3.0...v1.4.0).
• If a changelog tool owns the file, generate through it instead of editing by hand, and show the command used.

Report the version, the range covered, and any commits you deliberately excluded as noise, so the result is auditable.