| name | changelog |
|---|---|
| description | Write a user-facing changelog or release notes from a repository's git history between two refs. Use when the user asks to generate a changelog, release notes, or a summary of what changed between two versions, tags, or commits. |
Turn raw git history between two refs into a changelog written for the people who use the software, not the people who wrote it.
Read the history over the range the user gives you. Treat the starting ref as
exclusive and the ending ref as inclusive, which is the standard from..to
meaning in git.
git -C <repo> log <from>..<to> --pretty=format:'%h%x1f%an%x1f%aI%x1f%s%x1f%b%x1e'The fields are short hash, author, ISO date, subject, and body, separated by the unit separator, with each commit terminated by the record separator. If the user gives a single ref instead of a range, ask which two points they want compared rather than guessing.
A changelog is not a commit log. Most commits should not appear as their own line. Work through the commits and keep only what a user of the software would notice or act on.
Include changes that affect behavior the user can observe, such as new features, changed defaults, bug fixes for problems a user could have hit, performance changes they would feel, and anything that requires them to change how they use the software. Leave out changes that are invisible from outside, such as internal refactors, test-only changes, CI and tooling changes, dependency bumps with no user-facing effect, formatting, and the release-tag commit itself.
When a subject line is vague, read the body for the real change. When several commits together make one user-facing change, describe the change once rather than listing each commit.
Group the surviving entries by kind. Lead with the groups a reader cares about most, usually breaking changes first, then new features, then fixes, then everything else. Only include a group if it has entries.
Phrase every entry from the user's point of view and in the present tense. Describe what the software now does or no longer does, not what the committer did. Prefer "the retry option now respects a per-request timeout" over "fixed timeout handling in retry logic." Keep each entry to one line where you can. Do not include commit hashes or author names in the body of a normal changelog unless the user asks for attribution.
Flag anything that looks like a breaking change prominently, even if the commit did not label it as one, and say what the reader has to do about it.
Produce the changelog as Markdown, with a short heading for the range or version and one subsection per group. If the user named a version, use it in the heading. Keep the tone plain and factual. Do not invent changes that are not supported by the commits in the range, and if the range contains nothing user-facing, say so plainly rather than padding the changelog.