Ticket #244 (new enhancement)

Opened 5 years ago

Last modified 22 months ago

Add Changelog summary feature to sdist

Reported by: guest Owned by:
Priority: low Milestone:
Component: Cabal library Version: 1.2.3.0
Severity: normal Keywords:
Cc: gwern0@…, nomeata, kolmodin@…, ddssff@… Difficulty: normal
GHC Version: 6.8.2 Platform:

Description

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

Change History

  Changed 5 years ago by tibbe

We should also take other version control systems into account.

  Changed 5 years ago by 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.

  Changed 5 years ago by guest

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

-- gwern

follow-up: ↓ 5   Changed 5 years ago by 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

in reply to: ↑ 4   Changed 5 years ago by 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

  Changed 5 years ago by guest

  • cc gwern0@… added

  Changed 5 years ago by duncan

See also #299

  Changed 4 years ago by nomeata

  • cc nomeata added

  Changed 3 years ago by kolmodin

  • cc kolmodin@… added

  Changed 3 years ago by 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.

  Changed 3 years ago by 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.

follow-up: ↓ 13   Changed 3 years ago by 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... :-)

in reply to: ↑ 12   Changed 3 years ago by 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.)

  Changed 3 years ago by 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.

  Changed 22 months ago by dsfox

  • cc ddssff@… added
Note: See TracTickets for help on using tickets.