From d63e8258bc721909ddb709371c41c0a1fd22a105 Mon Sep 17 00:00:00 2001
From: Olivier Lacan <hi@olivierlacan.com>
Date: Sun, 31 Aug 2014 21:58:59 -0400
Subject: [PATCH] Some changes to sections and references.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 CHANGELOG.md | 45 +++++++++++++--------------------------------
 index.html   | 27 ++++++++++++++-------------
 2 files changed, 27 insertions(+), 45 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f193150e..0ef1b88c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,49 +1,30 @@
-# Changelog
+# Change Log
 All notable changes to this project will be documented in this file.
 
-## 0.0.3 - 2014-08-09
-
-### Added
-- "Why should I care?" section mentioning The Changelog podcast.
-
-### Deprecated
-- Nothing.
+## 0.0.4 - 2014-08-09
+### Changed
+- Refer to a "change log" instead of a "CHANGELOG" throughout the site
+to differentiate between the file and the purpose of the file — the
+logging of changes.
 
 ### Removed
-- Nothing.
+- Remove empty sections from CHANGELOG, they occupy too much space and
+create too much noise in the file. People will have to assume that the
+missing sections were intentionally left out because they contained no
+notable changes.
 
-### Fixed
-- Nothing.
+## 0.0.3 - 2014-08-09
+### Added
+- "Why should I care?" section mentioning The Changelog podcast.
 
 ## 0.0.2 - 2014-07-10
-
 ### Added
 - Explanation of the recommended reverse chronological release ordering.
 
-### Deprecated
-- Nothing.
-
-### Removed
-- Nothing.
-
-### Fixed
-- Nothing.
-
-
 ## 0.0.1 - 2014-05-31
-
 ### Added
 - This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
 - CNAME file to enable GitHub Pages custom domain
 - README now contains answers to common questions about CHANGELOGs
 - Good examples and basic guidelines, including proper date formatting.
 - Counter-examples: "What makes unicorns cry?"
-
-### Deprecated
-- Nothing.
-
-### Removed
-- Nothing.
-
-### Fixed
-- Nothing.
diff --git a/index.html b/index.html
index 029d314b..92cc2afa 100644
--- a/index.html
+++ b/index.html
@@ -25,34 +25,35 @@ <h3>Why should I care?</h3>
 (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 up a good CHANGELOG?</h3>
-<p>I’m glad you asked.</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>Versions should come with a release date in a sensible format: YYYY-MM-DD.</li>
-<li>Changes should be grouped to describe their impact on the project:
+<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>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>
-<li>Each section should be easily linked to — hence Markdown over plain text.</li>
-<li>Write release dates in an international, sensible, and language-independent 
-format: <code>2012-06-02</code> for <code>June 2nd, 2012</code>.</li>
-<li>Order the releases reverse chronologically (latest at the top).</li>
 </ul>
-<p>It’s also good to explicitly mention whether the project follows <a href="http://semver.org">Semantic Versioning</a>.</p>
 <h3>How can I minimize the effort required?</h3>
-<p>Always have an &quot;Unreleased&quot; section at the top for keeping notes on any
+<p>Always have an <code>&quot;Unreleased&quot;</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 &quot;Unreleased&quot; to the version number
-and add a new &quot;Unreleased&quot; header at the top.</li>
+<li>At release time, you just have to change <code>&quot;Unreleased&quot;</code> to the version number
+and add a new <code>&quot;Unreleased&quot;</code> header at the top.</li>
 </ul>
 <h3>What makes unicorns cry?</h3>
 <p>Alright…let’s get into it.</p>