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

[Ivan Lazar Miljenovic]

On 4 February 2013 20:02, Roman Cheplyaka <roma at ro-che.info> wrote:
> * 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

I would prefer _not_ specifying a format, primarily because people
might already have existing Changelog files in a differing format.
There's the GNU changelog format [1], the Debian changelog format [2],
and as an alternate I already use a Markdown-based format for graphviz
[3] so that I can convert it for the project's website [4].  As such,
it would be rather irritating for anyone who already has a Changelog
(or who might want to follow a different standard that they're used to
in future, e.g. because they want to include it as a Debian project)
just for some currently non-existent tooling.

That said, whilst I often hated writing them whilst I was at uni, in
hindsight something like this was a good use of JavaDoc-style tags.

[1]: http://www.gnu.org/prep/standards/html_node/Change-Logs.html
[2]: http://www.debian.org/doc/debian-policy/ch-source.html
[3]: http://hub.darcs.net/ivanm/graphviz/browse/Changelog.md
[4]: http://projects.haskell.org/graphviz/changelog.html

>
> Roman
>
> _______________________________________________
> Libraries mailing list
> Libraries at haskell.org
> http://www.haskell.org/mailman/listinfo/libraries



-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
http://IvanMiljenovic.wordpress.com