keep-a-changelog/README.md

# Keep a CHANGELOG

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

### What's a CHANGELOG?
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](assets/images/changelog_example.png)](CHANGELOG.md)

### 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 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:
  - `Added` for new features.
  - `Deprecated` for once stable features removed in upcoming releases.
  - `Removed` for deprecated features removed in this release.
  - `Fixed` for any bug fixes.
  - `Security` to 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-02` for `June 2nd, 2012`.
- Order the releases reverse chronologically (latest at the top).

It's also good to mention whether the project
follows [Semantic Versioning](http://semver.org/).

### What makes unicorns cry?
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](https://github.com/olivierlacan/keep-a-changelog/issues/new) 
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](CHANGELOG.md)
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, `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.

### 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](https://github.com/tech-angels/vandamme/) is a Ruby gem
created by the [Gemnasium](http://gemnasium.com) 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`](README.md), [`LICENSE`](LICENSE),
[`CONTRIBUTING`](CONTRIBUTING.md).

It denotes that these files are metadata for the project, similarly to
[open source project badges](http://shields.io/) 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](CHANGELOG.md) on [the GitHub repo](https://github.com/olivierlacan/keep-a-changelog),
I have purposefully not created a proper *release* or clear list of rules
to follow like [SemVer.org](http://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**](https://github.com/olivierlacan/keep-a-changelog/issues).