Basic

Writing a changelog

A changelog is for the person who is upgrading, not for the person who wrote the code. That means it lists what a consumer can assume, in the words a consumer uses, and it is written from the diff with the consumer's question in mind.

What you will see

The Removed line names the replacement, which is the line an upgrading consumer must not miss.

About 1 min of reading

Try It

Write the four groups.

1

The entry

print('''## v2.5.0 - 2026-10-01 ### Added - `--dry-run` on upload ### Removed - `legacy_save()` - use `save_v2()` instead ''')

Before you run it, say out loud what it will print. Then open the answer.

What it prints
The Removed line names the replacement, which is the line an upgrading consumer must not miss.

Put it in order

Before you write anything, put these lines back in the right order. Click a line to move it up one step. This support step is easier than writing code from scratch, and it is here to make the last example stick.

Data Flow

Commits become consumer lines.
1 List commits since the tag
↓
2 Group by impact
↓
3 Rewrite as consumer lines
↓
4 Ship the file with the release
Why this works
Generate then edit

Collect the commits since the last tag, then rewrite them as consumer facing lines. The generated list is the safety net that nothing was forgotten; the edit is what makes it readable.

Keep the file in the repo

The changelog ships with the code, so the release that added a feature and the line describing it are one diff apart. A changelog only on a website drifts, and drift is what makes it a lie.

Examples

Group by impact

Added, Changed, Fixed, Removed. Four groups, and a consumer reads the Removed one first, because that is where the breakage is. A flat list of commits buries that line in noise.

Name the breaking one

If something a consumer used to call is gone, it is named in Removed with the replacement. That is the only line an upgrading person cannot afford to miss, and it is the line most changelogs leave out.

Write the why

One clause on why a change happened lets a reader decide whether it applies to them. A changelog of what only is a changelog that answers no question.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Tagging a release in git
Previous Lesson
Tagging a release in git
Next Lesson
Pre-releases and the gap
Pre-releases and the gap →