Add Changelog summary feature to sdist

[guest]

In a discussion with Audrey Tang, she mentioned that a very nice feature of CPAN which she missed in Hackage was standardized changes files.

It seems to me that one way to acheive this would be to add a --changelog flag to sdist (or maybe make default). This call 'darcs changes' and copy into the ChangeLog? everything up to 2 tags ago. (2 tags because the first tag might be you preparing for a release). I'd imagine parsing would be dead easy: 'lines' to split it up into individual entries, and then take until you hit a 'tagged' entry. If the resulting list is length of 1, then take again.

So you'd go 'runhaskell Setup sdist --changelog', and ChangeLog? in the tarball would have, say, for Monadius:

---

Wed Feb 20 18:37:42 EST 2008 gwern0@…

tagged 0.91

Wed Feb 20 18:37:29 EST 2008 gwern0@…

• misc improvements: newtype, cabal, fmt

Fri Dec 7 16:23:53 EST 2007 gwern0@…

• rm extra source-files The line was originally there because there is an icon for Monadius in the source-files and some sort of Windows resource text file telling Windows to use it; I'm removing the mention of them in the .cabal because I don't think Cabal handles that right now.

Thu Dec 6 16:30:31 EST 2007 gwern0@…

• whitespace changes, add haskell98 to dependencies

Tue Dec 4 13:46:38 EST 2007 gwern0@…

• mv cabal field so hackage doesn't complain

Tue Dec 4 13:10:47 EST 2007 gwern0@…

• cabal fixes

Tue Dec 4 08:32:25 EST 2007 gwern0@…

tagged 0.91

---

At this point, Hackage could be updated to link to it in the same way as it does for the .cabal file. That way, people could then easily take a look and see what's new since the last version. (Said facility is currently a little difficult unless the package authors manually maintain a ChangeLog? and specifically include it into the tarball; you'd still have to either go to the repo or download the tarball simply to find out what's different from the older packages.)

--gwern

[tibbe]

We should also take other version control systems into account.

[guest]

It's worth noting that Darcs actually already has a little utility program which parses 'darcs changes'; it's probably a useful place to start.

[guest]

It's worth noting that I learned today there's an even better way: 'darcs changes --from-tag=.'.

-- gwern

[guest]

Anyway, to move things forward:

It isn't all that hard for most VCSes to extract 'everything since the last tag'.

As a matter of fact, I found it relatively easy to write a library/executable to do this for Darcs, Gits, and Mercurial. (Subversion and CVS are both much more difficult, and I just couldn't be bothered for Monotone, Codeville, or Bazaar.)

You can find it here:

 http://hackage.haskell.org/cgi-bin/hackage-scripts/package/change-monger-0.0

I hope y'all will consider incorporating the code into Cabal, or at least maybe adding some sort of option.

-- gwern

[guest]

Replying to guest:

I hope y'all will consider incorporating the code into Cabal, or at least maybe adding some sort of option. -- gwern

'Some sort of option' here being, I dunno, maybe an '--include=' option where you list a file to include in the sdist tarball regardless of whether it's mentioned in the cabal file or anything.

So you could at least do something like:

function sdist () { change-monger; cabal sdist --include=ChangeLog?; }

-- gwern

[duncan]

See also #299

[ross]

I think a VCS log would provide too much extraneous detail. You certainly wouldn't want to see it on the recent changes list. As a package user, I would want a short paragraph describing the user-visible changes (as requested in #299), e.g. for the above Monadius example:

Packaging fixes and internal cleanup: no change to API.

That seems to be the convention on CPAN, Debian, Gentoo, etc. Such a precis needs to be done manually, though the author would doubtless find VCS logs and API comparison tools useful as source material.

[guest]

ross: the nice thing about a VCS log is that it requires no developer intervention or effort. (Never underestimate laziness!) Ideally developers would give short perfect paragraphs summarizing every change. But expecting the ideal is a quick route to failure.

Further, it errs on the side of too much information; 'packaging fixes and internal cleanup' might hide important changes, like breaking backwards compatibility. It's easier to sort through excess information than conjure up information not there.

[nomeata]

I’m not sure if this is really a feature that should be integrated into Cabal. I’d welcome Cabal to define a standard changelog format, but a tool that automatically generates the entries ought to be separate from Cabal IMHO – Cabal does not include Darcs or an editor either... :-)

[guest]

Replying to nomeata:

I’m not sure if this is really a feature that should be integrated into Cabal. I’d welcome Cabal to define a standard changelog format, but a tool that automatically generates the entries ought to be separate from Cabal IMHO – Cabal does not include Darcs or an editor either... :-)

No effort, remember. Binding Darcs or editors into Cabal adds nothing - there is no obvious time for them to run nor obvious task to do. Generating a changelog for inclusion, though, is an obvious desideratum - like gzipping the tarball.

(Indeed, there is even more justification to scrap the gzipping part of sdist - it's merely a space optimization which could as well be done by users and which impacts no actual functionality or usability, unlike having or not having a changelog.)

[duncan]

I agree with Ross that a darcs changelog is far too much information. Much more that you could reasonably squeeze into an RSS feed entry for a new package.

A format for changelogs is reasonable, or if we can work out a convention such as showing the difference between the current and previous changelog file.

Personally I think the ideal thing would be a combination of a changelog written by the package author and an automatic API diff tool. The automatic API diff tool provides basic info and a human authored changelog can optionally provide helpful details / motivation / comments.