[commit: unix] master: change notes (1461d21)
Ivan Lazar Miljenovic
ivan.miljenovic at gmail.com
Mon Feb 4 11:18:55 CET 2013
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 , the Debian changelog format ,
and as an alternate I already use a Markdown-based format for graphviz
 so that I can convert it for the project's website . 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.
> Libraries mailing list
> Libraries at haskell.org
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
More information about the Libraries