[Haskell-cafe] Cabal and package changelog

[wren ng thornton]

Manlio Perillo wrote:
> Duncan Coutts ha scritto:
> > On Sun, 2009-03-08 at 10:00 -0400, Gwern Branwen wrote:
> > > http://hackage.haskell.org/trac/hackage/ticket/244
> > > http://hackage.haskell.org/trac/hackage/ticket/299
> >
> > Thanks Gwern. Yes, we're looking for a volunteer to work on implementing
> > this.
> > One question is what the changelog format should be? Or should it just
> > be uninterpreted text? One suggestion was for Hackage and the RSS feed
> > to display the diff between the current and previous version of the
> > changelog. Or perhaps we can do both, diff it and parse the result as
> > haddock markup or something.
> 
> Personally, I find a format like:
>     http://divmod.org/trac/browser/trunk/Nevow/NEWS.txt
> simple, compact and flexible.

Nice, simple, and to the point. It reminds me a lot of (a stripped down 
version of) YAML. If we invent a new format, using YAML as the syntax 
would make it easy to manipulate since there are already tools and 
libraries out there for that.


> GNU Changelog format is probably an overkill, since nowadays we have 
> good revision control systems.
> 
> However GNU Changelog format *may* be supported (perhaps the changelog 
> format can be specified in a Cabal property).

Like YAML, GNU Changelog has enough history to have a large suite of 
tools for manipulating the format. It's a bit heavy-handed in this day 
and age, but many VCSes can generate it automatically.



As a developer, one of my criteria would be to keep it as lightweight as 
possible (though more formal than raw text). The more work changelogs 
take, the less likely they are to be maintained/accurate.

As a UI issue, I would amend the proposal in ticket #244. Because of the 
way Darcs works around tag boundaries, I've often been lax about tagging 
more frequently than major versions. It'd be nicer to open up the 
pending changelog amendment in $EDITOR so people can adjust it before 
publishing the sdist. (Perhaps with a flag to enable/disable this 
behavior for people who want more automated setups.)

Also helpful would be a command to inject things into the changelog from 
outside the VCS, at times other than when publishing. This is helpful 
for when you realize a version control message omitted details about 
changes, but you can't change the patch, and you don't want to forget 
the details between now and when publishing the new sdist to Hackage. 
Essentially this means the tools should have a pending file for the 
changelog which can be freely modified outside of the system (with some 
in-system tracking so that importing the VCS log and editing it does the 
right thing when trying to import the VCS log again later).

Actually, just having a tool to amend the pending file could be enough. 
Most VCSes have hooks for being able to run things before or after 
committing a patch. Thus, just have a tutorial on setting up the common 
VCSes to commit the same message to the changelog as to the version control.

-- 
Live well,
~wren