How to Generate a Changelog With AI From Your Merged Changes

Step 1: Decide who reads it, and which window it covers

Two decisions up front, and everything downstream falls out of them. Who is this for, and what does it cover?

The audience is not "users" — it is a specific person with a specific problem. Someone upgrading a dependency and wondering what will break. An integrator whose parser stopped. A support rep working out whether a customer's complaint is a change or a bug. A teammate looking for when a behaviour changed. Those readers want different things, and the changelog can serve the first three at once if you decide that on purpose. It cannot also serve the person deciding whether to buy — that reader gets the announcement, and the moment you write for them, the entries start selling.

The window is the release boundary: which changes belong to this version and which belong to the last one or the next one. Not "everything merged since I last wrote one" — that is a calendar, not a release. If some of the merged work is behind a flag that is off, it did not ship, whatever the merge date says.

• Name the reader in one sentence before you write an entry. "Someone upgrading from 2.5 who integrates with our export" produces different entries than "our users."
• Fix the boundary as a pair of points, not a date range — the last published version and this one.
• Merged is not shipped. Anything behind an off flag, or reverted before the cut, is not in this release.
• If you cannot say which release a change is in, that is the question to answer first — not something to decide while writing.

Step 2: Collect the records, and mark what each one actually proves

Now gather the source material, and gather more of it than the merge list: merged PR summaries, the outcomes of the issues they closed, migration notes, deprecation decisions, security-relevant fixes, and any behaviour change someone flagged in review. The merge list is the skeleton. The issue an entry closed is usually where the user-visible symptom is actually described, because that is where the person who hit it wrote it down.

Then do the part that gets skipped: mark each record with what it proves. A PR title is a claim. The diff is the fact. The issue is a report of a symptom. A review comment saying "this changes the response shape" is a warning nobody has confirmed. These are different grades of evidence and a changelog treats them identically once they are entries, so the grading has to happen before.

Where a title and the change disagree, the title is wrong until someone who touched it says otherwise. This is common and it is not carelessness — a PR grows after it is named. "Fix nesting" ends up also changing a default. The title never got updated because the title had already done its job.

• Pull the closed issue, not just the PR. The symptom in the reader's words is usually already written there.
• Grade each record: what shipped (fact), what the title says (claim), what someone predicted in review (unconfirmed).
• A PR that closes an issue is one change with two records — you will merge them in Step 5, so keep them together now.
• When the record is thin, the answer is a question to its author, not a better guess.

Step 3: Cut everything the reader cannot observe

Most of what merged is invisible from outside, and it belongs in the commit history — where it already is, permanently, at no cost to anyone. The refactor, the dependency bump, the test helper, the queue library swap: none of it goes in unless a reader can observe something different.

The test is observability, not importance. A library swap that took three weeks and prevented a class of outage is enormous, and it still does not go in if nothing a user can see changed. Meanwhile a one-character default change goes in, because someone's Tuesday depends on it.

The interesting cases are the ones in between, and there is only one honest way to resolve them: ask the person who wrote it what a user would notice. If the answer is "nothing", it is out. If the answer is "well, jobs might come back in a different order now" — that is a Changed entry, and you nearly shipped a release that quietly reordered someone's pipeline.

• Ask what a reader could observe: an output, a shape, a timing, an error, a default, a limit.
• Effort is not the test. Big internal work with no observable effect stays internal.
• "Might" is an answer that needs its author, not a hedge you can write into an entry.
• Internal work does not need a changelog to be recognised — that is what the commit history and the team already are.

Step 4: Build the categories from what shipped

Added, Changed, Fixed, Deprecated, Removed, Security — the conventional set, and it is a menu rather than a form. The categories are supposed to describe this release. If nothing was removed, Removed is not an empty heading to be honest about; it is a heading that does not belong, and an empty one teaches readers to skim past headings.

This is where the Markdown Output Builder does the real work, and it is worth knowing what it does and does not hand you. Its changelog document type suggests five sections — Added, Changed, Fixed, Removed, Security — and enforces two rules that are the whole discipline in one line each: write each entry as a user-visible change rather than a commit message, and never bundle unrelated changes into one bullet. What it does not suggest is Deprecated. It is not one of the chips; if your release deprecates something, you add that section yourself and describe what belongs in it. That is not a workaround — the section list is yours to build, which is the point of the thing.

One detail worth understanding rather than fighting: the changelog preset ships with strict consistency, and strict does not mean "always five categories". It means the model may not drift from the skeleton you defined — no renaming your headings, no merging your sections, no dropping one because the content got thin. Strict is enforcement of your decisions, so make the decisions first and let it hold the line. Drop Removed in the builder and strict holds you to the four you kept.

• Decide the sections from the change list you just cut down, not from the convention.
• Add Deprecated by hand when the release deprecates something — the suggestions stop at five.
• An empty category is a lie of omission in reverse: it implies you checked and found nothing, when usually nobody looked.
• Security earns its place when something security-relevant shipped. A pinned empty Security section is a defensible house style — the packaged prompt takes that position deliberately — but it is a choice you should make on purpose rather than inherit.

Step 5: Write the entry as before, after, and what to do about it

An entry that says what changed is half an entry. The reader is not reading out of curiosity — they are working out whether this lands on them and what it costs. So the shape is: what it did before, what it does now, who that reaches, and what they have to do. Most entries end at "nothing to do", and saying so is the service.

Breaking changes carry the action or they are not finished. Not a warning — the action. "The export shape changed" is a warning. "`annotations` was an object keyed by id, it is now an array with the id inside each item, so build that map on your side; there is no compatibility flag" is an entry someone can act on at 9am without opening your source.

Granularity is decided by the reader, not by the merge list. Two PRs that produced one observable change are one entry. One PR that changed three unrelated things is three. A PR and the issue it closed are one entry with two references — and if you skip this merge, the same change appears twice in different words and the reader assumes two things broke.

Then reference it. Every entry gets a link to the PR or issue behind it, so the person who needs the detail can get it and the entry can stay short. Where you do not have the URL yet, a placeholder is fine — an unfilled placeholder is visible, and an omitted link is not.

• Before, after, who, and what to do. If "what to do" is nothing, write nothing — do not leave the reader to infer it.
• Give the action, not the alarm. A breaking change without its migration step is an announcement of a problem.
• One observable change is one entry, however many PRs produced it.
• Link every entry to its record. The entry is the summary; the link is the evidence.

Step 6: Park what nobody can stand behind

Some records will not survive the previous steps, and the temptation is to write a vague entry rather than an empty one. That is how "improved performance" gets published — a sentence with no measurement, no audience, and no way to be wrong, sitting next to entries that are all three.

Park it instead, visibly, with the reason and the person: excluded until its author says what got faster and how anyone knows. A parked entry costs one line in a draft nobody outside the team reads. A published unmeasured claim costs you the reader's trust in the entries that were true.

The date is the same discipline in a place people forget it is a claim. A changelog entry has a version and a date, and neither is yours to invent. Until the release publishes, the entries live under Unreleased — which is not a placeholder, it is an accurate statement about the world. When it publishes, Unreleased becomes the version and gets the date it actually happened. A date written on Wednesday for a Thursday release is a small fiction that ages into a real one when the release slips to the following week and nobody edits it back.

• Park with a reason and an owner: what is missing, and who can settle it.
• Unreleased is the honest home for anything not published yet. Promote it on the day, not before.
• Version numbers are a judgement about impact — whether the export break is major or minor is a decision your team owns, and it is not one to delegate to a draft.
• A deprecation without a removal date is a note nobody will ever schedule. If the date is unknown, that is the finding.

Step 7: Publish it the same way every time, and leave the old entries alone

A changelog earns its value by being in the same place, in the same shape, every release. Its usefulness is cumulative — someone scanning for when a behaviour changed is reading across versions, and every inconsistency between them is a place their eye stops. Same file, same categories where they apply, same entry shape, same level of detail.

Which leaves the rule people break with the best intentions: a published entry is a record, and records are not edited to become correct. If a v2.4.0 entry was wrong, the fix is a new entry in the current release saying what is actually true, not a quiet rewrite of history that leaves everyone who read the original holding a version of the past that no longer exists anywhere. The one exception is repair with a footprint — a correction noted as a correction, dated, so the change to the record is itself part of the record.

That is the difference between a changelog and a description of your software. A description should always be current. A ledger should be append-only, and a ledger silently rewritten is just a document.

• Same file, same shape, every release. The value is in the comparison across versions.
• Wrong published entry: correct it in the current release, do not rewrite the old one.
• If you must touch history, leave the correction visible and dated.
• Consistency beats completeness. A thorough changelog nobody can scan is worse than a plain one they can.