changeloop blog

Changelog automation, and its limits

Fri, 28 Aug 2026 00:00:00 GMT

Changelog automation projects fail in one of two directions, and both are predictable from the first design meeting.

Automate too little and the changelog is a document someone is supposed to update, which means it is updated in bursts, before releases, by whoever drew the short straw. Automate too much and it becomes a formatted git log: complete, accurate, and read by nobody.

The useful question is not how much to automate. It is which parts.

Four steps, and only three of them should be automatic

Collection. Getting changes out of the place they happen (commits, PRs, tickets) and into a list. Automate this completely. Humans are bad at it, it is tedious, and it is the step that gets skipped under deadline.

Classification. Deciding whether something is Added, Fixed, Changed, Deprecated, Removed or Security. Automate the first pass from commit type or PR label, and let a human override. Accuracy here is around eighty percent from metadata alone, and the wrong twenty percent is concentrated in exactly the entries that matter, because ambiguity correlates with significance.

Selection and wording. Deciding what a reader should be told and how to say it. Do not automate this. It is the entire value of the artifact. Everything else is logistics.

Publishing. Getting the finished entries to a page, a feed, an email, an in-app widget, a Slack channel. Automate completely, and from one source. This is where most of the manual effort actually goes, and almost nobody counts it.

That last point is worth sitting with. Teams tend to think of the changelog as a writing problem, then spend most of their time on distribution: copying entries into an email tool, reformatting for in-app, pasting into Slack, updating a docs page. The writing is an hour. The copying is an hour every release, forever, and it is the part a machine should have.

What happens when the line moves

Move it up and you get a git dump. Full automation from commits produces bump deps, fix flaky test, wip and address review comments in front of customers. Every team that has done this has then added a filter, and the filter is a selection step reintroduced under another name, with worse ergonomics.

Move it down and you get bursts. Fully manual collection means entries are written from memory at release time. That is the mode Keep a Changelog opens by warning about, and it degrades quietly: the changelog looks maintained right up until the week nobody had time.

A pipeline that holds

On merge, derive a draft entry from the PR: type from label or commit prefix, title as a first draft, link back to the PR, author recorded. Land it in an unreleased bucket.
Anyone can edit any draft at any time, and edits are cheap. Most get one line rewritten.
Cutting a release requires every entry in the bucket to be either edited or explicitly marked internal. This gate is the whole design. Without it, drafts ship unedited on the busy week.
Publishing is a fan-out from the released set: the public page, the feed, the email, the widget, the Slack post. One source, several renderings, no copying.

Step 3 is the only place a human is required, and it takes about ten minutes per release once the drafts are decent.

What this requires of your data

None of the above works if the changelog is a Markdown file, because a file cannot be rendered into five surfaces without parsing it back out, and parsing prose is how you end up with a widget that displays half a heading.

Entries need to be structured: a type, a date, a version or release identifier, an audience, a body and a link. Then the file, the page, the feed and the email are all views. That structural point is the one thing worth getting right before you pick a tool, because it is the thing you cannot retrofit cheaply.

We build changeloop, where the changelog is a feed first and a page second, so treat that as an interest rather than an impartial recommendation. Changelog tools is our roundup of what else is out there, including the products we compete with, and the changelog generator does the collection and classification steps in the browser if you want to see the shape before committing to a pipeline.

The test

Count the minutes between a change being merged and that change being visible to a customer who does not read your repo. If most of those minutes are someone copying text between tools, the automation you need is in publishing, not in writing.

Changelog vs release notes: what is the difference?

Fri, 28 Aug 2026 00:00:00 GMT

Most teams end up with one of these by accident and the other by request. You start with a changelog because a developer wants a record of what shipped. Months later someone in support asks why customers did not know about a feature that has been live since April, and now you need release notes.

They are not the same artifact, and the difference is not formatting. It is audience.

The short version

A changelog is a running, cumulative record of what changed. It is chronological, it is close to complete, and its reader has already decided they care. They are looking something up: when a behaviour changed, whether a bug is fixed, which version introduced a flag.

Release notes are a curated message about one release. They are selective, written in prose, and their reader has not decided anything yet. They are deciding whether this release matters to them, and whether they have to do anything about it.

One is a reference. The other is an announcement.

Side by side

	Changelog	Release notes
Reader	Someone looking something up	Someone deciding whether to care
Scope	Everything that changed	What is worth saying about this release
Cadence	Continuous, per merge or per release	Per release, and only releases worth announcing
Tone	Terse, factual, often imperative	Explanatory, sometimes persuasive
Lifespan	Permanent, and read years later	Read in the first week, then archived
Lives in	The repo, a docs site, a `/changelog` page	Email, in-app, a blog post, a release page
Fails by	Being incomplete	Being boring, or arriving after the fact

Why the confusion is reasonable

Small teams publish one artifact that does both jobs, and for a while that is correct. A single /changelog page with a short paragraph at the top of each entry will serve a developer looking up a fix and a customer skimming for news. Splitting too early gives you two things to maintain and one of them will rot.

The split becomes worth it when the two audiences start wanting different things. Some signs:

Your changelog entries have grown explanatory paragraphs that developers scroll past.
Or the opposite: your release announcements have started listing dependency bumps.
Support is copying entries into emails and rewriting them on the way.
Someone asks for "just the breaking changes" and you cannot filter for them.

That last one is the real tell. If nobody can answer "what changed that affects me" without reading everything, you have one artifact doing two jobs badly.

The version that works: one source, two views

The mistake is to treat them as two documents. They are two views over the same set of changes.

Write the changelog as you go, one entry per meaningful change, each tagged with what it is: fixed, added, changed, removed, deprecated, security. Keep the entries short enough that writing one is not a decision. Then, at release time, release notes are a selection and a rewrite: take the entries that matter to a human, group them by what they let someone do, and put the reason at the top.

This has a practical consequence. If the changelog is the source, it needs to be structured data, not a hand-maintained page. An entry needs a type, a date, a version, and a way of saying who it is for. Once it has that, the release notes email, the in-app widget and the public page are three renderings of one thing, and nobody rewrites anything on the way to a customer.

That is the whole argument for treating a changelog as a feed rather than a page. It is also, transparently, what we build, so read that as an interest rather than a neutral survey.

If you only have time for one

Write the changelog. It is cheaper per entry, it is useful the day you write it, and release notes can be derived from it later. The reverse is not true: you cannot reconstruct a year of changes from twelve announcement emails, and people will ask you to.

Keep it in a fixed format so the derivation stays possible. Our changelog examples page collects entries from teams that do this well, and the release notes template is the shape we use when turning a set of entries into something worth sending.

A note on naming

None of this is standardised, and you will find "release notes" used for a running list and "changelog" used for a quarterly announcement. Arguing about the words is not worth it. Decide which of the two jobs each of your artifacts is doing, name it whatever your team already calls it, and make sure neither is quietly doing both.

How to write release notes people actually read

Fri, 28 Aug 2026 00:00:00 GMT

Bug fixes and performance improvements.

Every product has shipped this. It is not lazy writing exactly. It is what you get when release notes are written from the inside, by someone who has spent two weeks in the diff and can no longer see which parts of it a stranger would care about.

The fix is not a better tone of voice. It is answering one question per entry.

The question

What can the reader do now that they could not do before, and what do they have to do about it?

If an entry cannot answer that, it belongs in the changelog and not in the release notes. Both halves matter. The first half is the value. The second half is the part teams forget, and it is the one that generates support tickets when it is missing.

Two examples of the second half doing real work:

"Existing webhooks keep working until 1 November. After that, unsigned payloads are rejected."
"No action needed. Existing exports are re-encoded automatically the next time you open them."

The second one says "no action needed" explicitly. That sentence is worth writing every single time, because a reader who cannot find it assumes the worst.

Order by consequence, not by component

The most common structural mistake is grouping by where the work happened: API, dashboard, mobile, infrastructure. That is your org chart, not the reader's problem.

Order it like this instead:

Breaking changes and anything with a deadline. First, always, even if it is small. If a reader stops after one line, this is the line they must have read.
What is new that they will want. One per paragraph, with the outcome in the first clause.
What got better. Fixes that were reported, limits that were raised, things that were slow.
Everything else, as a list. Dependency bumps, internal refactors, minor copy. One line each. Nobody reads this section, and it should still be there, because the person looking for it really needs it.

The rewrite

Before:

v4.2.0 Fixed an issue where the POST /exports endpoint would intermittently return 500 under load. Refactored the export worker. Bumped node-pg to 8.11. Improved error handling in the CSV serializer.

After:

Exports no longer fail on large accounts. Accounts over roughly 50,000 rows could get a 500 when starting an export, more often at month end. That is fixed, and exports of any size now retry themselves rather than failing. No action needed, and any export that failed in the last week can simply be run again.

Also in 4.2.0: node-pg 8.11, clearer CSV serializer errors.

Same release. The second one names the account that was affected, the time it was worst, what changed, and what to do. The dependency bump did not disappear, it just stopped being the headline.

Things worth deleting

"We are excited to announce." The reader is not excited yet. Earn it in the sentence after.
Internal ticket numbers. PROJ-4471 means nothing outside your tracker. If the entry needs a reference, link the docs page.
Component names only your team uses. If you renamed the "ingest pipeline", say "imports".
A version number as the only headline. v4.2.0 is a filing label, not a summary.
Screenshots of a settings page nobody has visited. Show the thing that changed, in use.

Cadence beats volume

Notes that arrive for every release train everyone to ignore them. Notes that arrive when something happened get opened. That means it is fine, and usually correct, to ship a release with no notes at all and roll its entries into the next set that has a headline worth reading.

The changelog still records all of it. That is the division of labour: the changelog is complete, the notes are selective. If you keep the changelog structured as you go, writing the notes is selection and rewriting rather than archaeology.

The release notes template is the shape we use for the selection step, and changelog examples collects entries from teams whose changelog is good enough to derive notes from.

One test before you publish

Read the notes as someone who has been on holiday for two weeks and has 40 seconds. If, in that time, they cannot tell whether anything is required of them, the notes are not finished, however accurate they are.

Release notes best practices worth keeping

Fri, 28 Aug 2026 00:00:00 GMT

Search for release notes best practices and you get style advice: be clear, be concise, use plain language, add screenshots. None of it is wrong and none of it changes anything, because no team has ever sat down intending to be unclear.

The practices below are the ones with a consequence. Each is followed by what it costs you if you skip it, because a practice without a failure mode attached is just a preference.

Practices that earn their place

Write the entry when you merge, not when you release. Cost of skipping: the person reconstructing the release from commit history is not the person who made the change, and they will guess at intent. Entries written a fortnight later are the ones that say "various improvements".

Say who is affected, by name. "Teams on the Business plan", "anyone using the v1 export API", "self-hosted installs on Postgres 14". Cost of skipping: every reader has to work out whether it applies to them, and most will decide it does not.

State the required action, including when it is none. Cost of skipping: support answers the same question forty times, and the readers who did not ask just assume something is required and put it off.

Give breaking changes a date, not a release number. "Removed in v5" means nothing to someone who does not know when v5 lands. "Stops working on 1 November" is a date they can put in a calendar. Cost of skipping: the deadline is discovered after it passes.

Keep one permanent, linkable entry per change. An email is not an archive and a Slack message is not a reference. Cost of skipping: nobody can answer "when did this change" six months later, including you.

Group by outcome, not by system. Cost of skipping: the reader has to hold your architecture in their head to work out which section matters to them.

Keep the boring section. Dependency bumps and internal changes stay, at the bottom, in one line each. Cost of skipping: the security team, the compliance reviewer and the person debugging a version mismatch all lose their only source.

Changelog best practices, which are not the same thing

A changelog is a reference, so its practices are about completeness and structure rather than persuasion:

A fixed entry type per line. Added, Changed, Deprecated, Removed, Fixed, Security. Not a house style, a filter: it is what lets someone ask for "just the breaking changes".
An unreleased section. Where entries live between merge and release. Its absence is why teams write entries late.
ISO dates. 2026-08-28, not 28/08/26, which means two different days depending on the reader.
One entry per change, not per commit. Three commits fixing one bug are one entry.

Three that are cargo cult

Emoji as entry types. A rocket and a wrench are not a taxonomy. They look tidy and they cannot be filtered, sorted, or read by a screen reader in any useful way. Use words, and if you want the emoji, put them after the word.

Semantic version numbers as headlines for a hosted product. Semver is a promise about API compatibility. For a SaaS product where nobody chooses their version, a version number in the headline is internal filing dressed up as news. Keep semver in the changelog and out of the announcement.

Publishing on a schedule regardless of content. Monthly notes with nothing in them teach people that your notes are noise. Publish when there is something to say. The changelog covers the rest.

The one that is actually hard

Keeping the changelog and the announcement in step, without writing everything twice.

Most teams start with one page, split it when the audiences diverge, and then quietly let one of the two rot, usually the changelog, because it is the one with no deadline attached. The way out is structural rather than disciplinary: keep the entries as data with a type, a date and an audience, and treat both surfaces as renderings of that. Our changelog tools roundup covers what is available for that, including the tools we compete with.

The release notes template is where the selection step lives once the entries exist.

If you adopt one thing

Write the entry at merge time, in a fixed format, with a type. Every other practice on this page gets easier once that one is in place, and none of them survive without it.

Keep a Changelog, actually implemented

Fri, 28 Aug 2026 00:00:00 GMT

Olivier Lacan published Keep a Changelog in 2014 with a line that has aged better than most software writing: don't let your friends dump git logs into changelogs. Ten years on it is the closest thing this corner of software has to a standard, which mostly means people cite it and then implement about two thirds of it.

It is worth reading the source rather than a summary of it. This is about the third that gets dropped.

What the spec actually asks for

A CHANGELOG.md at the repo root, newest first, with one section per version. Each version carries a number and an ISO date, and groups its entries under six types:

Type	For
Added	new features
Changed	changes in existing behaviour
Deprecated	features about to be removed
Removed	features removed in this release
Fixed	bug fixes
Security	vulnerabilities

Plus an Unreleased section at the top, so there is somewhere to put an entry the moment it is merged, and so anyone can see what is coming.

That is nearly all of it. The rest is the reasoning: entries are for humans, one entry per change, and the file is a document rather than a log.

The three parts that get dropped

Unreleased disappears first. It is the section with no deadline, so it is the one that stops being maintained, and once it is gone entries get written at release time from commit history. That is precisely the git-log dump the spec opens by warning about, arrived at gradually.

The six types collapse into two. Most real changelogs end up with Added and Fixed, because Changed and Deprecated require a judgement about what someone relied on. That judgement is the valuable part. Deprecated in particular is the only type that is a promise about the future, and dropping it is how a removal turns into an incident.

Security stops being separate. A security fix filed under Fixed is invisible to the one reader who was scanning for it. Keep it distinct even when the fix is trivial, and especially when you would rather not draw attention to it.

What the spec deliberately does not answer

It is a file format. It says nothing about the questions you hit immediately after adopting it:

How does anyone find out? A file in a repo reaches contributors. It does not reach a customer who has never opened GitHub.
What about products without versions? A continuously deployed service has no v4.2.0 to group by. Most teams substitute dates, which works, and the spec does not bless or forbid it.
Who writes the entry? The spec assumes a human does. It does not say when.
What about multiple audiences? One file serves developers. It does not serve the same content to a non-technical admin, and reformatting it by hand for them is where the duplication starts.

Common Changelog, a stricter fork of the idea, tightens some of this: it bans certain entry phrasings, requires a link to the change, and is opinionated about who the reader is. It is worth reading if the loose parts of Keep a Changelog are what your team keeps arguing about.

Automating it without dumping git logs

The spec's warning is about output, not about tooling. Deriving a draft from structured commits is fine. Publishing that draft unedited is the thing it objects to.

A shape that holds up: derive candidate entries from commits automatically, put them in Unreleased with their type prefilled, and require a human to edit the wording before a release can be cut. The machine handles collection and formatting, which it is good at. The human handles selection and phrasing, which it is not. Our changelog tools roundup covers what exists for the collection half.

Where it stops being enough

Keep a Changelog is a good answer to "what should this file look like". It is not an answer to "how do our users learn what changed", because a Markdown file in a repo is a distribution strategy that only works if your users are contributors.

That is the gap most teams hit second: the file is fine, and nobody outside the team reads it. Solving it means the entries have to become data that can be rendered somewhere else, which is a different problem from formatting a file, and the reason changelog examples collects public changelog pages rather than repo files.

Adopt the spec anyway. It costs an afternoon, it makes the second problem tractable, and it is still the best one page written about this.

From conventional commits to a changelog

Fri, 28 Aug 2026 00:00:00 GMT

feat(exports): add CSV column selection
fix(auth): reject expired refresh tokens
chore(deps): bump node-pg to 8.11

Three commits in the Conventional Commits format. From these, a machine can tell you that one is a feature, one is a fix, one is housekeeping, and which part of the system each touched. That is genuinely useful, and it is the entire promise of the convention: a commit history that can be read by something other than a person.

The mistake is thinking that gets you a changelog. It gets you the raw material.

What the convention actually specifies

A type, an optional scope, and a description: type(scope): description. Types are conventionally feat, fix, chore, docs, refactor, test, perf, build, ci. Two things mark a breaking change: a ! before the colon, or a BREAKING CHANGE: footer. Tooling keys off feat and fix for minor and patch version bumps, and off the breaking marker for a major.

It is a small spec and it is worth following even if you never generate anything from it, because it forces one decision per commit: is this a change users see, or not.

Where it stops

Commit messages are written for reviewers. fix(auth): reject expired refresh tokens is correct and tells a customer nothing. The reader of a changelog wants "you will be signed out when a session really has expired, instead of seeing intermittent 401s".

Scopes are internal. exports, auth, ingest are module names. They are stable, which makes them good for grouping, and meaningless to anyone outside the codebase.

One change is often several commits. A feature merged over eleven commits produces eleven entries, ten of which are noise, and squashing to hide that loses the review history.

chore is a bin, not a category. Dependency bumps, CI changes and renames all land there, and some of them matter to users while most do not.

So: the convention gives you type, scope and breaking status for free, and leaves wording, grouping and selection entirely open. Those three are the changelog.

The two-layer shape that works

Layer one, automatic. On merge, derive a draft entry from the commit: type mapped to a changelog type (feat to Added, fix to Fixed, a breaking marker to Changed plus a flag), scope kept as metadata rather than as text, link to the PR.

Layer two, human, and required. Before a release goes out, every draft entry either gets a one-line rewrite in the user's vocabulary, or gets marked internal and dropped from the public view. This is the step people try to skip, and skipping it is what produces changelogs that read like a diff.

The important design detail is that layer two is not optional in the pipeline. If a release can be cut with unedited drafts, it will be, on the week when everyone is busy.

Three traps

Squash merges eat the footers. If your platform squashes with the PR title as the message, the BREAKING CHANGE: footer from a commit inside that branch disappears, and your tooling silently stops seeing the breaking change. Check what your squash template actually keeps.

Revert commits produce phantom entries. A fix that is reverted the next day generates an entry for something that never shipped, unless the derivation reconciles reverts. Most tools do not.

Version bump and changelog get out of order. If the version is computed from commits and the changelog is written by hand afterwards, they drift within about two releases. Compute both from the same pass or accept that one of them is wrong.

If you want the mechanical part without a pipeline

Our changelog generator does the derivation step in the browser: paste commits, get grouped, typed entries out. It is deliberately deterministic and entirely client side, so the commits you paste never leave your machine, which matters when the messages are from a private repo. It does the collection half honestly and makes no attempt at layer two, because layer two is a judgement call and a tool that fakes it produces exactly the changelog this article is arguing against.

For the pipeline version, changelog tools has the landscape.

The summary

Conventional commits answer "what kind of change is this" reliably and cheaply. They do not answer "what should we tell people", and no amount of tooling on top of the commit message will, because the information was never in the commit message. Budget for the rewrite.