[Haskell-cafe] Cabal and package changelog
wren ng thornton
wren at freegeek.org
Sun Mar 8 22:22:04 EDT 2009
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:
> 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.
More information about the Haskell-Cafe