mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-15 23:08:14 +02:00
d63e8258bc
Including sections with no notables changes by putting a single "- Nothing." entry was a bad idea because for every single release this created a ton of noise. My only gripe with this decision is that users now have to assume that — for instance — the "Deprecated" section was intentionally left out because it contained nothing, while it's quite possible that they maintainers may not have deemed deprecations worthy of a change log entry. That's a problem because it makes expectations hard to manage. Another change I've made is that I now refer to a "change log" (lower case, two words) instead of a "CHANGELOG" (uppercase, one word) because I've released that the file is named "CHANGELOG" but the purpose of the file matters more than its name. Moreover the previous spelling made for awkward sentences and style.
128 lines
7.3 KiB
HTML
128 lines
7.3 KiB
HTML
<html>
|
||
<head>
|
||
<title>Keep a Changelog</title>
|
||
<link rel="stylesheet" href="assets/stylesheets/normalize.css" media="screen" charset="utf-8">
|
||
<link rel="stylesheet" href="assets/stylesheets/style.css" media="screen" charset="utf-8">
|
||
<script type="text/javascript" src="//use.typekit.net/tng8liq.js"></script>
|
||
<script type="text/javascript">try{Typekit.load();}catch(e){}</script>
|
||
</head>
|
||
<body>
|
||
<article>
|
||
<h1>Keep a CHANGELOG</h1>
|
||
<h2>Don’t let your friends dump git logs into CHANGELOGs™</h2>
|
||
<h3>What’s a CHANGELOG?</h3>
|
||
<p>A CHANGELOG is a file which contains a curated, chronologically ordered
|
||
list of notable changes for each version of an open source project.</p>
|
||
<p><a href="./CHANGELOG.md"><img src="assets/images/changelog_example.png" alt="Changelog Example"></a></p>
|
||
<h3>What’s the point of a CHANGELOG?</h3>
|
||
<p>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.</p>
|
||
<h3>Why should I care?</h3>
|
||
<p>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.</p>
|
||
<p>I <a href="http://5by5.tv/changelog/127">talked with Adam Stacoviak and Jerod Santo on The Changelog</a>
|
||
(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.</p>
|
||
<h3>What makes a good CHANGELOG?</h3>
|
||
<p>I’m glad you asked. </p>
|
||
<p>A good CHANGELOG sticks to these principles:</p>
|
||
<ul>
|
||
<li>It’s made for humans, not machines, so legibility is crucial.</li>
|
||
<li>Easy to link to any section (hence Markdown over plain text).</li>
|
||
<li>One sub-section per version.</li>
|
||
<li>List releases in reverse-chronological order (newest on top).</li>
|
||
<li>Write all dates in <code>YYYY-MM-DD</code> format. (Example: <code>2012-06-02</code> for <code>June 2nd, 2012</code>.) It’s international, sensible, and language-independent.</li>
|
||
<li>Explicitly mention whether the project follows <a href="http://semver.org">Semantic Versioning</a>.</li>
|
||
<li>Each version should:
|
||
<ul>
|
||
<li>List its release date in the above format.</li>
|
||
<li>Group changes to describe their impact on the project, as follows:</li>
|
||
<li><code>Added</code> for new features.</li>
|
||
<li><code>Deprecated</code> for once-stable features removed in upcoming releases.</li>
|
||
<li><code>Removed</code> for deprecated features removed in this release.</li>
|
||
<li><code>Fixed</code> for any bug fixes.</li>
|
||
<li><code>Security</code> to invite users to upgrade in case of vulnerabilities.</li>
|
||
</ul></li>
|
||
</ul>
|
||
<h3>How can I minimize the effort required?</h3>
|
||
<p>Always have an <code>"Unreleased"</code> section at the top for keeping track of any
|
||
changes.</p>
|
||
<p>This serves two purposes:</p>
|
||
<ul>
|
||
<li>People can see what changes they might expect in upcoming releases</li>
|
||
<li>At release time, you just have to change <code>"Unreleased"</code> to the version number
|
||
and add a new <code>"Unreleased"</code> header at the top.</li>
|
||
</ul>
|
||
<h3>What makes unicorns cry?</h3>
|
||
<p>Alright…let’s get into it.</p>
|
||
<ul>
|
||
<li><strong>Dumping a diff of commit logs.</strong> Just don’t do that, you’re helping nobody.</li>
|
||
<li><strong>Not emphasizing deprecations.</strong> When people upgrade from one version to
|
||
another, it should be painfully clear when something will break.</li>
|
||
<li><strong>Dates in region-specific formats.</strong> Americans put the month first
|
||
("06-02-2012" for June 2nd, 2012, which makes <em>no</em> sense), while Brits
|
||
use a robotic-looking "2 June 2012", yet pronounce it "June 2nd, 2012".</li>
|
||
</ul>
|
||
<p>There’s more. Help me collect those unicorn tears by
|
||
<a href="https://github.com/olivierlacan/keep-a-changelog/issues/new">opening an issue</a>
|
||
or a pull request.</p>
|
||
<h3>Is there a standard CHANGELOG format?</h3>
|
||
<p>Sadly, no. But I want to change that. </p>
|
||
<p>This project <a href="./CHANGELOG.md">contains what I hope will become the standard CHANGELOG file</a>
|
||
for all open source projects. Take a look at it, and please suggest improvements!</p>
|
||
<h3>What should the CHANGELOG file be named?</h3>
|
||
<p>Well, if you can’t tell from the example above, <code>CHANGELOG.md</code> is the
|
||
best convention so far.</p>
|
||
<p>Some projects also use <code>HISTORY.txt</code>, <code>HISTORY.md</code>, <code>History.md</code>, <code>NEWS.txt</code>,
|
||
<code>NEWS.md</code>, <code>News.txt</code>, <code>RELEASES.txt</code>, <code>RELEASE.md</code>, <code>releases.md</code>, etc.</p>
|
||
<p>It’s a mess. All these names only makes it harder for people to find it.</p>
|
||
<h3>Why can’t people just use a <code>git log</code> diff?</h3>
|
||
<p>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.</p>
|
||
<h3>Can CHANGELOG files be automatically parsed?</h3>
|
||
<p>It’s difficult, because people follow wildly different formats and file names.</p>
|
||
<p><a href="https://github.com/tech-angels/vandamme/">Vandamme</a> is a Ruby gem
|
||
created by the <a href="http://gemnasium.com">Gemnasium</a> team and which parses
|
||
many (but not all) open source project CHANGELOGs.</p>
|
||
<h3>Why do you keep writing CHANGELOG in all caps?</h3>
|
||
<p>You’re right, that is a bit shouty. Maybe it’s because of the <em>de facto</em>
|
||
convention: files pertaining to an open source project should be in
|
||
all caps. For instance: <a href="README.md"><code>README</code></a>, <a href="LICENSE"><code>LICENSE</code></a>,
|
||
<a href="CONTRIBUTING.md"><code>CONTRIBUTING</code></a>.</p>
|
||
<p>This indicates that these files are metadata for the project. Much like
|
||
<a href="http://shields.io">open source project badges</a>, they draw attention to
|
||
themselves as information to be aware of if someone intends to use
|
||
the project or contribute to it.</p>
|
||
<h3>How can I contribute?</h3>
|
||
<p>This document is not the <strong>truth</strong>; it’s my carefully considered
|
||
opinion, along with information and examples I gathered.
|
||
Although I provide an actual <a href="./CHANGELOG.md">CHANGELOG</a> on <a href="https://github.com/olivierlacan/keep-a-changelog">the GitHub repo</a>,
|
||
I have purposefully not created a proper <em>release</em> or clear list of rules
|
||
to follow (as <a href="http://semver.org">SemVer.org</a> does, for instance). </p>
|
||
<p>This is because I want our community to reach a consensus. I believe the
|
||
discussion is as important as the end result. </p>
|
||
<p>So please <a href="https://github.com/olivierlacan/keep-a-changelog/issues"><strong>pitch in</strong></a>.</p>
|
||
<footer class="clearfix">
|
||
<p class="license">This project is <a href="http://choosealicense.com/licenses/mit/">MIT Licensed</a>.</p>
|
||
<p class="about"><a href="https://github.com/olivierlacan/keep-a-changelog/">Typed</a> with trepidation by <a href="http://olivierlacan.com">Olivier Lacan</a> from <a href="http://codeschool.com">Code School</a>.</p>
|
||
</footer>
|
||
</article>
|
||
<script type="text/javascript">
|
||
var _gauges = _gauges || [];
|
||
(function() {
|
||
var t = document.createElement('script');
|
||
t.type = 'text/javascript';
|
||
t.async = true;
|
||
t.id = 'gauges-tracker';
|
||
t.setAttribute('data-site-id', '5389808eeddd5b055a00440d');
|
||
t.src = '//secure.gaug.es/track.js';
|
||
var s = document.getElementsByTagName('script')[0];
|
||
s.parentNode.insertBefore(t, s);
|
||
})();
|
||
</script>
|
||
</body>
|
||
</html>
|