Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

petdance (2468)

AOL IM: petdance (Add Buddy, Send Message)
Yahoo! ID: petdance (Add User, Send Message)

I'm Andy Lester, and I like to test stuff. I also write for the Perl Journal, and do tech edits on books. Sometimes I write code, too.

Journal of petdance (2468)

Wednesday August 30, 2006
02:15 PM

How not to do Changes files

[ #30809 ]
Here's how to not do a Changes file:

That tells me nothing about whether I want to upgrade my SpamAssassin install. :-(

Oh, look, I wrote about this before, and how great Tim Bunce's Changes files are:

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • I think this style of Changes file is alright if you don't care for anybody but you and maybe your fellow developers. Log files automatically generated by Subversion (or anything else) may be handy if you just don't have the time, but they do not add much than a few lines with a (possibly) incomplete list of bug fixes and new features.
  • the more human-readable brief changelog in the announcement is probably what you want:!-tf2190657 .html []

    • That should be included in the distro then.


    • I agree with Andy.

      For open source software, if I want to see the subversion log, I'll just go to the public subversion and look at the real subversion log.

      For the Changes file, what really matters is the human summary.

      Posting it to an insiders (as in people who have previously signed up to specifically keep track of the project) is far less useful that adding it so that everyone can see it.
      • Um, the announcement mail is linked from [] -- the front page of the project website. hardly an "insiders list"...

        the point that it should appear in the distro, though, is well made.

        FWIW, the "svn log" format Changes file that we use is indeed useful, even if that data is available from svn; assuming otherwise assumes that (a) the user can access the svn repository and is online etc, (b) the repository will always be available (what happens in 20 years time?), and (c) they know
        • Your point about the subtleties of the svn log are pretty reasonable.

          Perhaps just putting it in something like a "svn.log" file rather than the Changes file (By convention generally for human consumption) would be better?
  • Perhaps I'm splitting hairs a bit too much, but IMHO "Changes" should tell you INTERESTING things that have changed since the last release (or rather, the last time you updated the VERSION number.) Having a file that captures things which are
    1) only of interest to the project's developers, and
    2) precisely what said developers could learn by running svn/cvs/p4/etc 'log' command
    seems entirely superfluous. Better to not have the "Changes" file at all, in that case.

    My $0.02,
  • I always get depressed when I click on the Changes link and find something that I can't scan for reasons to update or possible sources of a new bug. It might be useful to include things like an XML-style changelog or a summary of the actual svn commits, but they should be someplace other than Changes, which tradition has made into a standard "release notes" summary.