mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-15 23:08:14 +02:00
133 lines
7.9 KiB
HTML
133 lines
7.9 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 change log?</h3>
|
||
<p>A change log 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" title="An example of a CHANGELOG file."><iframe src="CHANGELOG.md" width="570" height="350" seamless="seamless" style="border: 1px solid #aaa; padding: 1em; margin: 0 0.5em;"></iframe></a></p>
|
||
<h3>What’s the point of a change log?</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 change log?</h3>
|
||
<p>I’m glad you asked.</p>
|
||
<p>A good change log 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, <a href="http://xkcd.com/1179/">sensible</a>, 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".
|
||
"2014-06-02" works logically from largest to smallest, and doesn't overlap
|
||
in ambiguous ways with other date formats, and thus is the recommended
|
||
date format for change logs.</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 change log 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 change log 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 change logs 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 change logs.</p>
|
||
<h3>Why do you alternate between spelling it "CHANGELOG" and "change log"?</h3>
|
||
<p>"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
|
||
historical convention followed by many open source project. Other
|
||
examples of similar files include <a href="README.md"><code>README</code></a>, <a href="LICENSE"><code>LICENSE</code></a>,
|
||
and <a href="CONTRIBUTING.md"><code>CONTRIBUTING</code></a>.</p>
|
||
<p>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 <a href="http://shields.io">open source project badges</a>.</p>
|
||
<p>When I refer to a "change log", I'm talking about the function of this
|
||
file: to log changes.</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>
|