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

What’s a change log?

A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](

## [Unreleased]
### Added
- RU translation from @aishek.
- pt-BR translation from @tallesl.

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can benefit
both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer]( properly.

## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.

### Changed
- Clarified the section on "Is there a standard change log format?".

### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.

## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.

## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## 0.0.1 - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"


What’s the point of a change log?

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.

Why should I care?

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 maintainers and contributors should care, and the motivations behind this project. If you can spare the time (1:06), it’s a good listen.

What makes a good change log?

I’m glad you asked.

A good change log sticks to these principles:

How can I minimize the effort required?

Always have an "Unreleased" section at the top for keeping track of any changes.

This serves two purposes:

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 change log format?

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 sadly 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. I don't think the status quo is good enough, and I think that as a community we can come up with better conventions if we try to extract good practices from real software projects. Please take a look around and remember that discussions and suggestions for improvements are welcome!

What should the change log 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. All these names 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 — 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.

Can change logs be automatically parsed?

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.

Why do you alternate between spelling it "CHANGELOG" and "change log"?

"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.

What about yanked releases?

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.

Should you ever rewrite a change log?

Sure. There are always good reasons to improve a change log. I regularly open pull requests to add missing releases to open source projects with unmaintained change logs.

It's also possible you may discover that you forgot to address a breaking change in the notes for a version. It's obviously important for you to update your change log in this case.

How can I contribute?

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 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.