[commit: unix] master: change notes (1461d21)

[Roman Cheplyaka]

* Ian Lynagh <ian at well-typed.com> [2013-02-04 01:06:38+0000]
> On Mon, Feb 04, 2013 at 12:43:40AM +0000, Ben Millwood wrote:
> > On Mon, Feb 04, 2013 at 09:49:42AM +1100, Ivan Lazar Miljenovic wrote:
> > >>Hmm. I think it would be better to have Cabal/haddock understand a
> > >>CHANGES file in a particular format. That way haddock (and hackage)
> > >>could show the recent changes on a package's page, with a link to the
> > >>full history, and the description can remain just a description of what
> > >>the package does.
> > >
> > >Or even just a link to the raw text file on Hackage.
> > 
> > Hackage 2 actually already does this! See the link at the bottom of
> > http://hackage.factisresearch.com/package/haskell-src-meta :)
> > 
> > Not exactly what you'd call prominent, but definitely a good start.
> 
> Right, I'm not sure it's prominent enough for what Simon wanted.
> 
> A parsable format would allow hackage (and haddock, when invoked by
> cabal) to show the changes for just the last release on the main page.
>
> It would also mean that, on hackage's 'full changelog' page, it could
> turn the headings for each release into links to the hackage page for
> that particular release.

Sounds great!

As for the format, may I propose markdown (which is pretty much the
standard these days), where level 2 headers denote versions?

Something like

  # Changes

  ## 1.4

  * add 'foo'
  * remove 'bar'

  ## 1.3
  
  * add 'bar'
  
  ...

The benefit is that such a changelog would be also rendered
automatically on github and similar sites. Plus, no need to invent our
own format.

Support for free-form headers, like "Version 1.4" or "v1.4" would also be nice.

Here's an example: https://github.com/feuerbach/smallcheck/blob/master/CHANGES.md

Roman