MiniProfiler/rack-mini-profiler — pull request #83 by olivierlacan (2014-06-03 17:00:25+00:00)
Title: Reorganize and format the CHANGELOG with Markdown

Why Markdown? Because CHANGELOGs are for humans and GitHub
parses Markdown beautifully.

Why subheadings (h2) for each release? Because that empasizes them and
makes them automatically hyperlinked, which is extremely useful whenever
you need to reference notable changes for a specific version.

Why change the date format to YYYY-MM-DD? Because it's self-explanatory
and not regionally-bound.

Why put the version first and the date second? Because the date is metadata
while the version is the key piece of information. The individual list
items are the value for that key.

You'll not that there are several release dates for which no version is
given. I could not find those versions and it's a shame because I don't
see how one can find a release without the version number, I hope someone
can correct this.

There are a few instances where the type of change was been given, as for
version 1.30 where there is a "feature" change and a "bug" change. I have
not formatted those differently yet because there are two interesting
approaches to this (very important) qualification:

1. One can use `[BUG]` in front of a change to denote that it's a a bugfix
although `[FIX]`, `[FIXED]`, or `[BUGFIX]` seem far more sensible. `[BUG]`
can be misinterpreted as the introduction of a bug, not the fixing of it.
2. I sometimes think that it would make more sense to make each possible
type of change (Added, Deprecated, Removed, Fixed, etc.) its own
sub-heading (h3 in this case) and next the appropriate changes underneath
when they exist, otherwise indicate "Nothing." to clearly indicate — for
instance — that nothing was deprecated in this release.

Both approaches are valid, the second one is certainly more tedious.

I offer more context on the thoughts behind this commit here: keepachangelog.com