Add recommendantion for reverse chronological ordering.

Also bump version to 0.0.2 as a good excuse to show an example of
this reverse chronological ordering.

CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## 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

README.md

@@ -3,13 +3,13 @@
 ## Don’t let your friends dump git logs into CHANGELOGs™
 
 ### What's a CHANGELOG?
-A CHANGELOG is a file which contains a curated chronologically ordered 
+A CHANGELOG is a file which contains a curated chronologically ordered
 list of notable changes for each version of an open source project.
 
 [![Changelog Example](assets/images/changelog_example.png)](CHANGELOG.md)
 
 ### What's the point of a CHANGELOG?
-To make it easier for users and contributors to see precisely what 
+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.
 
 ### What makes up a good CHANGELOG?
@@ -25,66 +25,67 @@ I'm glad you asked.
   - `Fixed` for any bug fixes.
   - `Security` to invite users to upgrade in case of vulnerabilities.
 - Each section should be easily linked to — hence Markdown over plain text.
-- Write release dates in an international, sensible, and 
+- Write release dates in an international, sensible, and
 language-independent format: `2012-06-02` for `June 2nd, 2012`.
+- Order the releases reverse chronologically (latest at the top).
 
-It's also good to mention whether the project 
+It's also good to mention whether the project
 follows [Semantic Versioning](http://semver.org/).
 
 ### 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 
+- Not emphasizing deprecations: when people upgrade from one version to
 another it should be painfully clear when something will break.
-- Dates in regionally-specific formats. Americans put the month first 
-("06-02-2012" for June 2nd, 2012, which makes *no* sense), while Brits 
-use a robotic-looking "June 2 2012", yet pronounce it "June 2nd, 2012". 
+- Dates in regionally-specific formats. Americans put the month first
+("06-02-2012" for June 2nd, 2012, which makes *no* sense), while Brits
+use a robotic-looking "June 2 2012", yet pronounce it "June 2nd, 2012".
 
 There's more. Help me collect those unicorn tears by 
 [opening an issue](https://github.com/olivierlacan/keep-a-changelog/issues/new) 
 or a pull request.
 
 ### Is there a standard CHANGELOG format?
-Sadly, no, but this is something I want to change. This project 
-[contains what I hope will become the standard CHANGELOG file](CHANGELOG.md) 
+Sadly, no, but this is something I want to change. This project
+[contains what I hope will become the standard CHANGELOG file](CHANGELOG.md)
 for all open source projects, so take a look at it and please suggest improvements.
 
 ### What should the CHANGELOG file be named?
-Well, if you can't tell from the example above, `CHANGELOG.md` is the 
+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`, 
+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, that 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. Can we really expect every single 
-commit in an open source project to be meaningful and self-explanatory? 
+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.
 
 ### Can CHANGELOG files be automatically parsed?
-It's hard because people follow wildly different formats and file names. 
-[Vandamme](https://github.com/tech-angels/vandamme/) is a Ruby gem 
-created by the [Gemnasium](http://gemnasium.com) team and which parses 
+It's hard because people follow wildly different formats and file names.
+[Vandamme](https://github.com/tech-angels/vandamme/) is a Ruby gem
+created by the [Gemnasium](http://gemnasium.com) team and which parses
 many (but not all) open source project CHANGELOGs.
 
 ### Why do you keep writing CHANGELOG in all caps?
-You're right, that is a bit shouty. Maybe it's because of the de facto 
-convention that files pertaining to an open source project should be in 
-all caps, for instance: [`README`](README.md), [`LICENSE`](LICENSE), 
+You're right, that is a bit shouty. Maybe it's because of the de facto
+convention that files pertaining to an open source project should be in
+all caps, for instance: [`README`](README.md), [`LICENSE`](LICENSE),
 [`CONTRIBUTING`](CONTRIBUTING.md).
 
-It denotes that these files are metadata for the project, similarly to 
-[open source project badges](http://shields.io/) they draw attention to 
-themselves as information people should be aware of if they mean to use 
+It denotes that these files are metadata for the project, similarly to
+[open source project badges](http://shields.io/) they draw attention to
+themselves as information people should be aware of if they mean to use
 the project or contribute to it.
 
 ### How can I contribute?
-This document is not the **truth**, it's my carefully considered 
+This document is not the **truth**, it's my carefully considered
 opinion with the information and examples I was able to gather. Although
 I provide an actual [CHANGELOG](CHANGELOG.md) on [the GitHub repo](https://github.com/olivierlacan/keep-a-changelog),
-I have purposefully not created a proper *release* or clear list of rules 
-to follow like [SemVer.org](http://semver.org/) does for instance. This is 
-because I want our community to reach a consensus. I believe the discussion 
+I have purposefully not created a proper *release* or clear list of rules
+to follow like [SemVer.org](http://semver.org/) 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**](https://github.com/olivierlacan/keep-a-changelog/issues).

index.html

@@ -11,11 +11,11 @@
 <h1>Keep a CHANGELOG</h1>
 <h2>Don’t let your friends dump git logs into CHANGELOGs&trade;</h2>
 <h3>What&#39;s a CHANGELOG?</h3>
-<p>A CHANGELOG is a file which contains a curated chronologically ordered 
+<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&#39;s the point of a CHANGELOG?</h3>
-<p>To make it easier for users and contributors to see precisely what 
+<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>What makes up a good CHANGELOG?</h3>
 <p>I&#39;m glad you asked.</p>
@@ -32,59 +32,60 @@ <h3>What makes up a good CHANGELOG?</h3>
 <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 
+<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&#39;s also good to mention whether the project 
+<p>It&#39;s also good to mention whether the project
 follows <a href="http://semver.org/">Semantic Versioning</a>.</p>
 <h3>What makes unicorns cry?</h3>
 <p>Alright, let&#39;s get into it:</p>
 <ul>
 <li>Dumping a diff of commit logs. Just don&#39;t do that, you&#39;re helping nobody.</li>
-<li>Not emphasizing deprecations: when people upgrade from one version to 
+<li>Not emphasizing deprecations: when people upgrade from one version to
 another it should be painfully clear when something will break.</li>
-<li>Dates in regionally-specific formats. Americans put the month first 
-(&quot;06-02-2012&quot; for June 2nd, 2012, which makes <em>no</em> sense), while Brits 
-use a robotic-looking &quot;June 2 2012&quot;, yet pronounce it &quot;June 2nd, 2012&quot;. </li>
+<li>Dates in regionally-specific formats. Americans put the month first
+(&quot;06-02-2012&quot; for June 2nd, 2012, which makes <em>no</em> sense), while Brits
+use a robotic-looking &quot;June 2 2012&quot;, yet pronounce it &quot;June 2nd, 2012&quot;.</li>
 </ul>
 <p>There&#39;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 this is something I want to change. This project 
-<a href="CHANGELOG.md">contains what I hope will become the standard CHANGELOG file</a> 
+<p>Sadly, no, but this is something I want to change. This project
+<a href="CHANGELOG.md">contains what I hope will become the standard CHANGELOG file</a>
 for all open source projects, so take a look at it and please suggest improvements.</p>
 <h3>What should the CHANGELOG file be named?</h3>
-<p>Well, if you can&#39;t tell from the example above, <code>CHANGELOG.md</code> is the 
+<p>Well, if you can&#39;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>, 
+<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.
 It&#39;s a mess, that only makes it harder for people to find it.</p>
 <h3>Why can&#39;t people just use a git log 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? 
+<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&#39;s hard because people follow wildly different formats and file names. 
-<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 
+<p>It&#39;s hard because people follow wildly different formats and file names.
+<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&#39;re right, that is a bit shouty. Maybe it&#39;s because of the de facto 
-convention that 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>, 
+<p>You&#39;re right, that is a bit shouty. Maybe it&#39;s because of the de facto
+convention that 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>It denotes that these files are metadata for the project, similarly to 
-<a href="http://shields.io/">open source project badges</a> they draw attention to 
-themselves as information people should be aware of if they mean to use 
+<p>It denotes that these files are metadata for the project, similarly to
+<a href="http://shields.io/">open source project badges</a> they draw attention to
+themselves as information people should be aware of if they mean 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&#39;s my carefully considered 
+<p>This document is not the <strong>truth</strong>, it&#39;s my carefully considered
 opinion with the information and examples I was able to gather. 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 like <a href="http://semver.org/">SemVer.org</a> does for instance. This is 
-because I want our community to reach a consensus. I believe the discussion 
+I have purposefully not created a proper <em>release</em> or clear list of rules
+to follow like <a href="http://semver.org/">SemVer.org</a> 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 <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>