diff --git a/source/en/0.4.0/index.html.haml b/source/en/0.4.0/index.html.haml new file mode 100644 index 0000000..81c6c36 --- /dev/null +++ b/source/en/0.4.0/index.html.haml @@ -0,0 +1,183 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: en +version: 0.4.0 +--- + +:markdown + # Keep a Changelog + + ## Don’t let your friends dump git logs into changelogs™ + + Version **#{current_page.metadata[:page][:version]}** + + ### 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. + +%pre.changelog= File.read("CHANGELOG.md") + +:markdown + ### 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][thechangelog] + (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: + + - 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-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent. + - Explicitly mention whether the project follows [Semantic Versioning][semver]. + - Each version should: + - List its release date in the above format. + - Group changes to describe their impact on the project, as follows: + - `Added` for new features. + - `Changed` for changes in existing functionality. + - `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. + + ### 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: + + - 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. + + ### 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 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](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it + is the recommended date format for change logs. + + There’s more. Help me collect those unicorn tears by + [opening an issue][issues] + 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][CHANGELOG]. + 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][issues]! + + ### What should the change log 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. 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][vandamme] is a Ruby gem + created by the [Gemnasium][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`][README], [`LICENSE`][LICENSE], + and [`CONTRIBUTING`][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][shields]. + + 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][gh], + I have purposefully not created a proper *release* or clear list of rules + to follow (as [SemVer.org][semver] 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**][gh]. + + [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md + [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md + [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE + [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md + [gemnasium]: https://gemnasium.com/ + [gh]: https://github.com/olivierlacan/keep-a-changelog + [issues]: https://github.com/olivierlacan/keep-a-changelog/issues + [semver]: http://semver.org/ + [shields]: http://shields.io/ + [thechangelog]: http://5by5.tv/changelog/127 + [vandamme]: https://github.com/tech-angels/vandamme/