How to write a changelog for your project

If you are asking how to write a changelog for your project, the short answer is this: keep one file, list changes newest first, group them under plain categories, and write each entry so a user can tell what changed for them. That is all a good changelog needs.

If you want somewhere to publish release notes and the thinking behind them, Electrified lets you make an account and write articles on your own page, with topics, a feed, and follows. The rest of this guide covers the changelog itself.

Write a changelog for your project: what it is and why you need one

A changelog is a dated list of what changed in each version of your project. It is not your commit history. Commits are written for the people who build the project. A changelog is written for the people who use it.

You need one because users want the same answers after every release. What is new? Did something break? Do I need to change my setup? If the answers sit in one place, you do not have to give them one by one.

Three kinds of reader open it.

• Users want to know if a release fixes their bug or adds something they asked for.
• Maintainers and contributors want a record of what shipped and when.
• Anyone upgrading wants to know what could break.

The third group matters most. They are about to change something that works. Put the risky items where they cannot miss them.

Choose a changelog format and file location

Use a plain text file in the root of your repository. The usual name is CHANGELOG.md. Markdown reads well on its own and renders cleanly almost everywhere.

Order matters. Put the newest version at the top, so the release a reader cares about most is the first thing they see.

Pick one format and stay with it. A simple layout, following the Keep a Changelog convention, is:

• A title and one line saying what the file is.
• An ## Unreleased section at the top for changes not yet shipped.
• One ## heading per version, with the version number and release date.

If you also write longer posts about big releases, keep the file short and link to those posts from it. The file stays a quick reference, and the post carries the story.

Group changes into clear categories

A flat list of 30 lines is hard to scan. Sort entries under a few headings inside each version. These work for most projects:

• Added for new features.
• Changed for changes to existing behavior.
• Deprecated for things that will be removed later.
• Removed for things that are gone.
• Fixed for bug fixes.
• Security for vulnerability fixes.

Leave out any heading with nothing under it. A release with two fixes needs one heading, not six.

Write entries people can understand

Write each entry from the user's side. Say what they can now do, or what no longer goes wrong. Skip internal names unless the user sees them.

A weak entry and a better one

Weak: Refactor parser module, fix null check in tokenizer.

Better: Fixed a crash when importing an empty file.

The first describes the work. The second describes the result. A user cannot act on the first.

Rules that keep entries useful

• Start with a verb: Added, Fixed, Removed.
• Keep it to one line where you can.
• Name the command, option, or setting that changed, in code formatting.
• Link the issue or pull request if there is one, so curious readers can dig in.
• Do not paste commit messages. Rewrite them.

Handle versions, dates, and breaking changes

Give every release a version number and a date. Write the date in a form that cannot be misread, such as 2026-10-21. Year, month, day avoids confusion between regions.

If you use semantic versioning, the number tells readers what to expect. A major bump says something may break. A minor bump says new features, nothing broken. A patch says fixes only. Your changelog should match what the number promises.

For breaking changes, do more than list them. Put them first in the version, label them clearly, and say what to do. For example:

Breaking: Removed the --legacy flag. Use --compat instead. Scripts that pass --legacy will now exit with an error.

That one entry names what went, what replaces it, and what happens if the reader does nothing. When you deprecate something, announce it one release before you remove it, and list it under Deprecated so nobody is surprised.

Keep your changelog up to date with less effort

A changelog written months later is a changelog full of gaps. A few habits keep it current.

1. Update it with each change. Add a line under Unreleased in the same pull request as the code. You still remember what it does.
2. Make it part of review. If a pull request changes behavior and the changelog is untouched, ask for the line.
3. Release by renaming. When you ship, rename Unreleased to the new version and date, then add a fresh empty Unreleased above it.
4. Read it before you tag. Two minutes of reading catches vague lines and missing breaking changes.

Tools can draft entries from commits, but treat the result as raw material. Edit it into sentences a user would understand.

Changelog template you can copy

Copy this layout into CHANGELOG.md and replace the examples with your own entries. Each line below is one line in the file.

• # Changelog
• All notable changes to this project are listed here, newest first.
• ## Unreleased
• ### Added
• - Describe a new feature.
• ## 1.2.0 - 2026-10-21
• ### Changed
• - Describe a change to existing behavior.
• ### Fixed
• - Fixed a crash when importing an empty file.
• ## 1.1.0 - 2026-09-30
• ### Added
• - Added the --compat option.

Once the file exists, you can turn a major release into a longer article. Explain why you made a change, show a before and after, and link to the changelog for the full list. Writing a run of articles like this is also a way to build knowledge around a topic, and the same habit of clear, direct writing applies to other writing guides.

Frequently asked questions

Should a changelog list every commit?

No. List only changes a user could notice. Internal cleanups and refactors that change nothing for the user can stay in the commit history.

Where should the changelog file go?

In the root of your repository, named CHANGELOG.md. That is the usual name and place, so readers know where to look.

How is a changelog different from release notes?

A changelog is a running, structured list of every release. Release notes are usually a single write-up for one release, with more context. You can keep both and link one to the other.

How do I show a breaking change?

Put it at the top of the version, label it Breaking, and say what to do instead. Name the old option and the new one.

Can I write my release notes on Electrified?

Yes. An article can have a title and as many sections as it needs, and you can add up to 5 topics of your own choosing. Your posts also get an Atom feed at /@handle/feed.xml.

Get started

Create CHANGELOG.md today, paste in the template, and add your last three releases from memory or from your tags. Then add one line for every change from now on.

Make an account on Electrified: write about your product, topic or idea on your own page, one article at a time, and let readers follow along.