j2labs/schematics — pull request #166 by bdickason (2013-09-23 21:16:54+00:00)
Title: Add a simple Changelog (Resolves #164)

I created a simple Changelog (called HISTORY.rst) so we can track changes between various versions and there's a clear path to see which issues were resolved with each version number.

As inspiration I used Fabric's changelog: http://docs.fabfile.org/en/latest/changelog.html

It is QUITE beautiful and links nicely back to Github issues and versions (which we don't have a concept of in Schematics). However, the way they solved adding nice color is by using .RST directives which Github does not properly interpret. The result is a nice-looking Sphinx/RST changelog (http://docs.fabfile.org/en/latest/changelog.html) that looks crappy on Github (https://github.com/fabric/fabric/blob/master/docs/changelog.rst).

In this release, I opted for universally usable. We can change this in the future, if desired.

The other Changelog I looked at was what TJ Holowaychuk uses for all of his Node projects (example: https://github.com/visionmedia/mocha/blob/master/History.md). He maintains 500+ open source projects and somehow manages to keep the changelog up to date so I thought it would be a good reference.

We might want to consider adding a "??? / ???" at the top to allow developers to add their changes into Changelog as they commit. If not, whoever cuts the release version has to go back and figure out what fixes go into this release.