Don’t let your friends dump git logs into CHANGELOGs™


A CHANGELOG is a file which contains a curated chronologically ordered list of notable changes for each version of an open source project.

Changelog Example

What's the point of a CHANGELOG?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

What makes up a good CHANGELOG?

I'm glad you asked.

It's also good to mention whether the project follows Semantic Versioning.

What makes unicorns cry?

Alright, let's get into it:

There's more. Help me collect those unicorn tears by opening an issue or a pull request.

Is there a standard CHANGELOG format?

Sadly, no, but this is something I want to change. This project contains what I hope will become the standard CHANGELOG file for all open source projects, so take a look at it and please suggest improvements.

What should the CHANGELOG file be named?

Well, if you can't tell from the example above, is the best convention so far.

Some projects also use HISTORY.txt,,, NEWS.txt,, News.txt, RELEASES.txt,,, etc. It's a mess, that only makes it harder for people to find it.

Why can't people just use a git log diff?

Because log diffs are full of noise. Can we really expect every single commit in an open source project to be meaningful and self-explanatory? That seems like a pipe dream.

Can CHANGELOG files be automatically parsed?

It's hard because people follow wildly different formats and file names. Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project CHANGELOGs.

Why do you keep writing CHANGELOG in all caps?

You're right, that is a bit shouty. Maybe it's because of the de facto convention that files pertaining to an open source project should be in all caps, for instance: README, LICENSE, CONTRIBUTING.

It denotes that these files are metadata for the project, similarly to open source project badges they draw attention to themselves as information people should be aware of if they mean to use the project or contribute to it.

How can I contribute?

This document is not the truth, it's my carefully considered opinion with the information and examples I was able to gather. Although I provide an actual CHANGELOG on the GitHub repo, I have purposefully not created a proper release or clear list of rules to follow like does for instance. This is because I want our community to reach a consensus. I believe the discussion is as important as the end result. So please pitch in.