A change log 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.
Because software tools are for people. If you don’t care, why are you contributing to open source? Surely, 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.
A good change log sticks to these principles:
- It’s made for humans, not machines, so legibility is crucial.
- Easy to link to any section (hence Markdown over plain text).
- One sub-section per version.
- List releases in reverse-chronological order (newest on top).
- Write all dates in
YYYY-MM-DDformat. (Example:2012-06-02forJune 2nd, 2012.) It’s international, sensible, and language-independent. - Explicitly mention whether the project follows Semantic Versioning.
- Each version should:
- List its release date in the above format.
- Group changes to describe their impact on the project, as follows:
Addedfor new features.Changedfor changes in existing functionality.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.
Always have an "Unreleased" section at the top for keeping track of any
changes.
This serves two purposes:
- People can see what changes they might expect in upcoming releases
- At release time, you just have to change
"Unreleased"to the version number and add a new"Unreleased"header at the top.
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 region-specific formats. In the U.S., people put the month first ("06-02-2012" for June 2nd, 2012, which makes no sense), while many people in the rest of the world write a robotic-looking "2 June 2012", yet pronounce it differently. "2012-06-02" works logically from largest to smallest, doesn't overlap in ambiguous ways with other date formats, and is an ISO standard. Thus, it is the recommended date format for change logs.
There’s more. Help me collect those unicorn tears by opening an issue or a pull request.
Sadly, no. Calm down. I know you're furiously rushing to find that link to the GNU change log style guide, or the two-paragraph GNU NEWS file "guideline". The GNU style guide is a nice start but it is naive. There's nothing wrong with being naive but when people need guidance it's rarely very helpful. Especially when there are many situations and edge cases to deal with.
This project contains what I hope will become a better CHANGELOG file convention for all open source projects. Can the open source community learn from its mistake and not act as if the ten commandments were written long ago and got everything right? Alright. So please take a look around and remember that discussions and suggestions for improvements are welcome!
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. All these names only makes it harder for people to find it.
Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states.
As is the difference between good comments and the code itself, so is the difference between a change log and the commit log: one describes the why, the other the how.
It’s difficult, 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 change logs.
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
historical convention followed by many open source projects. Other
examples of similar files include README, LICENSE,
and CONTRIBUTING.
The uppercase naming (which in old operating systems made these files stick to the top) is used to draw attention to them. Since they're important metadata about the project, they could be useful to anyone intending to use or contribute to it, much like open source project badges.
When I refer to a "change log", I'm talking about the function of this file: to log changes.
Yanked releases are versions that had to be pulled because of a serious bug or security issue. Often these versions don't even appear in change logs. They should. This is how you should display them:
## 0.0.5 - 2014-12-13 [YANKED]
The [YANKED] tag is loud for a reason. It's important for people to
notice it. Since it's surrounded by brackets it's also easier to parse
programmatically.
This document is not the truth; it’s my carefully considered opinion, along with information and examples I gathered. 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 (as 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.