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

On 4 February 2013 20:02, Roman Cheplyaka wrote:

* Ian Lynagh [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@haskell.org http://www.haskell.org/mailman/listinfo/libraries

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