A CHANGELOG is a file which contains a curated chronologically ordered list of notable changes for each version of an open source project.
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.
Well, because software tools are for people. If you don't care, why are you contributing to open source? There must be a kernel (ha) of care somewhere in that lovely little brain of yours.
I talked with Adam Stacoviak and Jerod Santo on The Changelog (fitting, right?) podcast about why open source maintainers and contributors should care, and the motivations behind this project. If you can spare the time (1:06), it's a good listen.
I'm glad you asked.
- It's made for humans, not machines, so legibility is crucial.
- One sub-section per versions.
- Versions should come with a release date in a sensible format: YYYY-MM-DD.
- Changes should be grouped to describe their impact on the project:
Addedfor new features.Deprecatedfor once stable features removed in upcoming releases.Removedfor deprecated features removed in this release.Fixedfor any bug fixes.Securityto invite users to upgrade in case of vulnerabilities.
- Each section should be easily linked to — hence Markdown over plain text.
- Write release dates in an international, sensible, and
language-independent format:
2012-06-02forJune 2nd, 2012. - Order the releases reverse chronologically (latest at the top).
It's also good to mention whether the project follows Semantic Versioning.
Alright, let's get into it:
- Dumping a diff of commit logs. Just don't do that, you're helping nobody.
- Not emphasizing deprecations: when people upgrade from one version to another it should be painfully clear when something will break.
- Dates in regionally-specific formats. Americans put the month first ("06-02-2012" for June 2nd, 2012, which makes no sense), while Brits use a robotic-looking "June 2 2012", yet pronounce it "June 2nd, 2012".
There's more. Help me collect those unicorn tears by opening an issue or a pull request.
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.
Well, if you can't tell from the example above, CHANGELOG.md is the
best convention so far.
Some projects also use HISTORY.txt, HISTORY.md, History.md, NEWS.txt,
NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.
It's a mess, that only makes it harder for people to find it.
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.
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.
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.
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 SemVer.org 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.