Changelog Template: Release Notes for Developers, Users and Breaking Changes
A changelog is a dated list of what changed in each release, written for the person who has to decide whether to upgrade or what to expect. Keep one entry per release, group changes by type, write in the reader’s words and link anything that needs detail. Use the CHANGELOG.md template for developers, the release-note template for non-technical users, and the breaking-change notice whenever an update can stop something working.
Why keep a changelog in the weeks after a launch?
Because the first month of a product’s life is mostly small fixes made because of what people told you, and a changelog is how they find out. Someone who reported a bug and sees it listed three days later has a reason to come back and mention it to a friend. Someone who finds nothing changes their mind about whether the project is alive. A visible record of steady, small releases also answers a question every careful visitor has: is this maintained?
A changelog is not a git log. Commit messages are written for the person making the change, and a changelog is written for the person living with it. The Keep a Changelog site makes the same point in its subtitle, and it also proposes the common headings used in the first template below. We read it on 13 November 2026.
Template 1: CHANGELOG.md for developers
This follows the Keep a Changelog layout: newest release first, an Unreleased section on top, a date in ISO form and the headings Added, Changed, Deprecated, Removed, Fixed and Security. If you number releases, the Semantic Versioning rule is to raise the major number for incompatible API changes, the minor number for backward-compatible functionality and the patch number for backward-compatible fixes.
# Changelog All notable changes to [project name] are recorded here. ## [Unreleased] ### Added - [Feature in progress, only if you want to show it] ## [0.2.0] - [YYYY-MM-DD] ### Added - [What a user can now do, in a verb phrase] ([link to issue]) ### Changed - [What behaves differently, and the old behaviour in brackets] ### Fixed - [The bug in terms of what the user saw, not the cause] ([link to issue]) ## [0.1.0] - [YYYY-MM-DD] - First public release.
Write each line as the effect on someone using the project: “Fix crash when the config file is empty” rather than “Handle null in parseConfig”. If the cause matters, link to the commit or issue instead of explaining it inline.
Template 2: release notes for people who are not developers
Users of a web app or a tool do not read a changelog file. They see a short note on the site, in the app or in an email, and they skim it. Write for them in plain language, lead with the change they asked for and leave out the internals.
What's new in [product name], [date] You asked for it: - [Feature or fix, described as what you can now do. Name the person or the request type if they agreed: "Thanks to everyone who asked."] Improved: - [A thing that got faster, clearer or easier, with the specific place it changed] Fixed: - [A problem people hit, described in the words they used when they reported it] Still on the list: [one or two things people ask for that you have not done yet, honestly]. Something not working? Reply to this note or [where to report].
Template 3: a breaking-change notice
Anything that can stop existing use from working, such as renaming a setting, changing an output format or dropping support for a version, needs its own notice and not a line buried in a list. The readers who matter most are the ones who will be hurt. Tell them before they find out the hard way.
BREAKING: [one-sentence summary of what changes] (in [version], [date]) Who is affected: [exactly who: anyone using X, anyone on version Y or older] What breaks: [the specific behaviour, with the error message people will see] Why: [one honest sentence] How to fix it: 1. [Step one, with the exact command or setting] 2. [Step two] Before: [old usage] After: [new usage] Need more time? [How long the old behaviour stays, if it does, and where to ask.]
What habits keep a changelog useful?
- Write the entry as you make the change, not at release time. Memory fades quickly and the entry gets vague.
- One entry per release, with a real date. Undated lists look abandoned and make it impossible to match a bug report to a version.
- Credit the person who reported it, with their permission. It costs a sentence and brings people back.
- Do not list every commit. If a change is invisible to the user, leave it out, or group it under one “internal” line.
- Do not rewrite history. If an entry was wrong, add a correction in the next release instead of deleting the old line.
- Link the changelog from the product, the repository and the launch page, so people can find it without asking.
Where should the changelog live?
For libraries and tools: a CHANGELOG.md in the repository, linked from the README, as in the README template for a launch. For web products: a simple public page on your own site, plus a line in your launch page description or a comment when something important ships. You can launch your product free once the changelog page exists, so the description can link to it from the first day. A published launch is final, which is one more reason to link a page you control and keep updating. The post-launch checklist and the launch a v2 of your product playbook show how updates feed later announcements, and the developer tool ideas on the board give a sense of what people ask developers to build.
Frequently asked questions
Is a changelog the same as release notes?
They overlap, but the audience differs. A changelog is a complete, dated record usually kept in a file, aimed at people who track the project. Release notes are a short, friendly summary of one release, aimed at users. Many small products keep one source and write the friendly version from it.
Do I need a changelog before my first launch?
No, but start one the day you publish. A single line saying “first public release” with a date gives the file a beginning, and you will thank yourself later when you need to match a bug report to a version. Adding entries from day one is easier than reconstructing them.
Should I use version numbers or just dates?
Use numbers if people install your software as a dependency, and follow a known scheme such as semantic versioning. For a hosted web app, dates alone are usually enough, since everyone is on the latest version. Whichever you choose, always include a date so entries can be placed in time.
How do I handle bugs I introduced?
Record them like any other fix, in plain words: what went wrong, who was affected and what changed. If the bug caused data loss or a security problem, give it its own notice with steps to recover. Honesty about mistakes in a changelog builds more trust than a spotless record that nobody believes.
Written by Post your build ideas with AI assistance and edited for this site. Where a page names another product, the facts came from that product’s own pages on the date shown above; terms change, so check them before you rely on them. About the publisher.