mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-19 00:38:34 +02:00
212 lines
12 KiB
HTML
212 lines
12 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 id="keep-a-changelog">
|
||
<a name="keep-a-changelog" class="anchor" href="#keep-a-changelog"></a>
|
||
Keep a CHANGELOG
|
||
</h1>
|
||
<h2 id="don-t-let-your-friends-dump-git-logs-into-changelogs-">
|
||
<a name="don-t-let-your-friends-dump-git-logs-into-changelogs-" class="anchor" href="#don-t-let-your-friends-dump-git-logs-into-changelogs-"></a>
|
||
Don’t let your friends dump git logs into CHANGELOGs™
|
||
</h2>
|
||
<h3 id="what-s-a-change-log-">
|
||
<a name="what-s-a-change-log-" class="anchor" href="#what-s-a-change-log-"></a>
|
||
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 a 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 id="what-s-the-point-of-a-change-log-">
|
||
<a name="what-s-the-point-of-a-change-log-" class="anchor" href="#what-s-the-point-of-a-change-log-"></a>
|
||
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 id="why-should-i-care-">
|
||
<a name="why-should-i-care-" class="anchor" href="#why-should-i-care-"></a>
|
||
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 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 id="what-makes-a-good-change-log-">
|
||
<a name="what-makes-a-good-change-log-" class="anchor" href="#what-makes-a-good-change-log-"></a>
|
||
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>Changed</code> for changes in existing functionality.</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 id="how-can-i-minimize-the-effort-required-">
|
||
<a name="how-can-i-minimize-the-effort-required-" class="anchor" href="#how-can-i-minimize-the-effort-required-"></a>
|
||
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 id="what-makes-unicorns-cry-">
|
||
<a name="what-makes-unicorns-cry-" class="anchor" href="#what-makes-unicorns-cry-"></a>
|
||
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> In the U.S., people put the month first
|
||
("06-02-2012" for June 2nd, 2012, which makes <em>no</em> 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
|
||
<a href="http://www.iso.org/iso/home/standards/iso8601.htm">ISO standard</a>. Thus, it
|
||
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">opening an issue</a>
|
||
or a pull request.</p>
|
||
<h3 id="is-there-a-standard-change-log-format-">
|
||
<a name="is-there-a-standard-change-log-format-" class="anchor" href="#is-there-a-standard-change-log-format-"></a>
|
||
Is there a standard change log format?
|
||
</h3>
|
||
<p>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.</p>
|
||
<p>This project <a href="./CHANGELOG.md">contains what I hope will become a better CHANGELOG file convention</a>.
|
||
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
|
||
<a href="https://github.com/olivierlacan/keep-a-changelog/issues">discussions and suggestions for improvements are welcome</a>!</p>
|
||
<h3 id="what-should-the-change-log-file-be-named-">
|
||
<a name="what-should-the-change-log-file-be-named-" class="anchor" href="#what-should-the-change-log-file-be-named-"></a>
|
||
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 id="why-can-t-people-just-use-a-code-git-log-code-diff-">
|
||
<a name="why-can-t-people-just-use-a-code-git-log-code-diff-" class="anchor" href="#why-can-t-people-just-use-a-code-git-log-code-diff-"></a>
|
||
Why can’t people just use a <code>git log</code> diff?
|
||
</h3>
|
||
<p>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.</p>
|
||
<p>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 <em>why</em>, the other the how.</p>
|
||
<h3 id="can-change-logs-be-automatically-parsed-">
|
||
<a name="can-change-logs-be-automatically-parsed-" class="anchor" href="#can-change-logs-be-automatically-parsed-"></a>
|
||
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 id="why-do-you-alternate-between-spelling-it-quot-changelog-quot-and-quot-change-log-quot-">
|
||
<a name="why-do-you-alternate-between-spelling-it-quot-changelog-quot-and-quot-change-log-quot-" class="anchor" href="#why-do-you-alternate-between-spelling-it-quot-changelog-quot-and-quot-change-log-quot-"></a>
|
||
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 projects. 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 id="what-about-yanked-releases-">
|
||
<a name="what-about-yanked-releases-" class="anchor" href="#what-about-yanked-releases-"></a>
|
||
What about yanked releases?
|
||
</h3>
|
||
<p>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:</p>
|
||
<p><code>## 0.0.5 - 2014-12-13 [YANKED]</code></p>
|
||
<p>The <code>[YANKED]</code> 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.</p>
|
||
<h3 id="should-you-ever-rewrite-a-change-log-">
|
||
<a name="should-you-ever-rewrite-a-change-log-" class="anchor" href="#should-you-ever-rewrite-a-change-log-"></a>
|
||
Should you ever rewrite a change log?
|
||
</h3>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
<h3 id="how-can-i-contribute-">
|
||
<a name="how-can-i-contribute-" class="anchor" href="#how-can-i-contribute-"></a>
|
||
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"><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>
|