On Sat, Aug 13, 2011 at 5:18 AM, Ivan Lazar Miljenovic wrote:

On 13 August 2011 20:57, Joachim Breitner wrote:

...

Maybe it would already help to add a "changelog-file" field to .cabal, just as with license-file, and reject packages on hackage that do not have this field and file, and later decide if we need a more standardized format for changelogs.

I agree, but it would be nice to also have optional readme-file, todo-file and doc-files fields (the latter to let us avoid banging documentation in with "extra-source-files").

As for a standardised format... I'm not sure if we need to enforce a particular format, as long as it's understandable.

Debian's packaging has a very strict changelog format where each entry combines a log entry with the package name, the version number, the author's name and email, and the date. This creates a very nice, centralized, authoritative source for these pieces of information that can't be accidentally omitted or allowed to become stale.

Hi, Am Sonntag, den 14.08.2011, 00:29 +1000 schrieb Ivan Lazar Miljenovic:

On 14 August 2011 00:25, David Fox wrote:

...

Debian's packaging has a very strict changelog format where each entry combines a log entry with the package name, the version number, the author's name and email, and the date. This creates a very nice, centralized, authoritative source for these pieces of information that can't be accidentally omitted or allowed to become stale.

Is this for the actual Debian packages, or even for source tarballs that they get from upstream?

it’s for the packaging work, here is an example: http://packages.debian.org/changelogs/pool/main/g/ghc/ghc_7.0.4-4/changelog But I think David is suggesting to adapt a similarly formatted changelog file for Cabal packages, e.g. to display them on hackage. I am all for that, as long as it does not prevent the introduction of changelogs (e.g. by excessive bikeshedding or by having people lose interest again). Greetings, Joachim -- Joachim "nomeata" Breitner mail@joachim-breitner.de | nomeata@debian.org | GPG: 0x4743206C xmpp: nomeata@joachim-breitner.de | http://www.joachim-breitner.de/

On 14 August 2011 01:13, Joachim Breitner wrote:

But I think David is suggesting to adapt a similarly formatted changelog file for Cabal packages, e.g. to display them on hackage. I am all for that, as long as it does not prevent the introduction of changelogs (e.g. by excessive bikeshedding or by having people lose interest again).

I think to an extent it might, as those people who already have changelogs of one kind or another would then have to go and re-format them (disclaimer: my changelog for graphviz is currently in Markdown so that I can make a web version of it: http://projects.haskell.org/graphviz/changelog.html ). -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com

On 8/13/11 5:39 PM, Joachim Breitner wrote:

Hi,

Am Samstag, den 13.08.2011, 12:57 +0200 schrieb Joachim Breitner:

...

Maybe it would already help to add a "changelog-file" field to .cabal, just as with license-file, and reject packages on hackage that do not have this field and file, and later decide if we need a more standardized format for changelogs.

here is a first step in improving the Haskell ecosystem with that regard: The patch attached to http://hackage.haskell.org/trac/hackage/ticket/873 makes "cabal check" remind the author that a changelog file is good practice (without fixing a name or format, or adding a field to the .cabal file). I hope it gets applied (hence CC’ing cabal-devel).

Changing developers’ behavior by nudging tools is something that works great in Debian – if you want a change to get implemented across multiple packages, make sure lintian tells you about it. Hoping that people tend to run cabal check before uploading their package, they would now be reminded to include a changelog file.

+1.

The next steps towards great changes documentation would then be: * Defining a changelog-file field in cabal. * Adding support to hackage to display the changelog. * Possibly define a suggested format for changelogs.

At the risk of overengineering, perhaps the easiest way to deal with format bikeshedding is just to define an enumeration of formats just like the enumeration of licenses. That way machine-readable formats are annotated by which machine should read them, but crotchety developers don't have to change their changelogging preferences. After that's in place, then we can worry about the social pressure to get the community to agree on a smaller set of formats (just like has happened with licenses). -- Live well, ~wren