guides

A changelog is a file that lists the notable changes made to a project, organised by version. Its job is to answer a simple question for anyone using or depending on your software: what changed between the version I had and the version I am moving to. Because it is written for people rather than machines, a good changelog highlights what actually matters to users and leaves out the noise.

It helps to be clear about what a changelog is not. It is not the raw output of your version control history. A git log lists every commit, including tiny refactors, typo fixes, and merge commits, in the order they were made and in whatever wording the author happened to use. A changelog is a curated, human-written summary that groups related work, drops the trivial details, and describes each change in terms of its effect on the person reading it.

The most widely followed convention for writing one is called Keep a Changelog. It sets out a plain format based on Markdown, usually in a file named CHANGELOG.md at the root of the repository. The idea is that a consistent, predictable structure makes the file easy to scan, whether a reader is a person browsing on a code host or a tool parsing the entries.

The Keep a Changelog format

Under that convention, each released version gets its own section headed by the version number and the date it was released. Within a version, changes are grouped under a small set of standard headings so readers can find what they care about quickly. The recommended groups are Added for new features, Changed for changes to existing behaviour, Deprecated for features that are on their way out, Removed for features that are now gone, Fixed for bug fixes, and Security for anything relating to vulnerabilities.

The versions themselves usually follow Semantic Versioning, so a version reads as MAJOR.MINOR.PATCH, such as 2.4.1. This ties the changelog to the version number in a useful way: a reader can look at the jump from one version to the next and form an expectation. A change in the major number signals that something may break, while a patch bump suggests only fixes. The changelog then explains, in words, exactly what sits behind that number.

Ordering, dates, and the Unreleased section

A changelog is normally kept in reverse chronological order, with the newest version at the top so the most relevant information is the first thing a reader sees. Each entry is dated, which lets people place a release in time and understand how recent a fix or feature is. Keeping the ordering and the dates consistent is part of what makes the file trustworthy at a glance.

• A changelog is a file listing the notable changes in each version, written for people, not the raw git log.
• Keep a Changelog is the common convention, usually a CHANGELOG.md in Markdown at the repository root.
• Standard change groups: Added, Changed, Deprecated, Removed, Fixed, and Security.
• Versions typically follow Semantic Versioning (MAJOR.MINOR.PATCH), each with its release date.
• Entries go in reverse chronological order, often with an Unreleased section at the top.
• You can generate entries from commits (for example Conventional Commits), but a hand-written changelog is often clearer.

A common and practical addition is an Unreleased section at the very top. This is where you record changes as you make them, before they are tied to a version number. When you are ready to publish a release, you rename that section to the new version, give it a date, and start a fresh Unreleased block. This habit means the changelog is written while the work is fresh, rather than reconstructed from memory at the last minute.

Writing good entries and generating them

Writing good entries is mostly about keeping the reader in mind. Each notable change should get its own entry, phrased so that someone who does not know the internals can still understand the effect. It is worth describing the outcome for the user rather than the mechanics of the code, avoiding internal jargon, and grouping related edits into a single clear line instead of one entry per commit. Trivial or purely internal changes can be left out entirely.

It is possible to generate a changelog automatically from your commit history, and many teams do. Approaches like Conventional Commits ask you to write commit messages in a structured way, for example prefixing them with feat or fix, so a tool can sort them into the right groups and assemble a draft. This can save time and enforce consistency, but the output tends to read like a list of commits. A changelog that is written or at least edited by hand is often clearer, because a person can decide what is worth mentioning and phrase it for the audience.

Summary

In short, a changelog is a human-readable record of what changed in each version of a project, kept for the people who use it. The Keep a Changelog convention gives it a predictable shape, Semantic Versioning gives its version numbers meaning, and a little discipline, such as an Unreleased section and one entry per notable change, keeps it accurate. Whether written by hand or generated from commits, its value comes from being clear, current, and focused on what the reader actually needs to know.