All the Perl that's Practical to Extract and Report

Uselessnes of Changelogs

ethan on 2003-05-13T09:03:45

I just saw that a new Mail::SpamAssassin release has hit the CPAN. Unfortunately I am unable to conclude from the changelog whether I should upgrade or not. Can anyone but the developpers themselves learn anything from this?

2003-05-10 20:38 felicity

* Changes: Updated for 2.54rc1

2003-05-10 18:05 duncf

* lib/Mail/SpamAssassin.pm: Ready to release?

2003-05-10 17:34 felicity

* rules/: 20_head_tests.cf, 30_text_de.cf, 30_text_fr.cf, 30_text_it.cf, 50_scores.cf, 70_broken_rules.cf: bug 1891: RCVD_IN_VISI is no longer available

For me this is as interesting and enlighting as reading CVS log messages which the above probably are.

Please, people out there, provide sane Changelogs for the end-user and not for yourselves!

Good point

jonasbn on 2003-05-13T09:43:12

I really like your point.

Write the CHANGES file for your audience and not for yourself.

You write a manual, you write POD, you write code, you write tests, you write a piece of software with audience in mind, then when it comes to the CHANGES file - all this changes and things get very simplified and incomprehensible (at least in your example).

I will go over my changes file to see whether I make the same mistake.

Re:Good point

rafael on 2003-05-13T10:15:17

More precisely, provide a CHANGE file for users and a ChangeLog for developers.

I like the Writing log messages guidelines from Subversion's HACKING internal guide.

But sometimes, log messages that are just plain funny are sufficient.

Re:Good point

ethan on 2003-05-13T11:34:58

More precisely, provide a CHANGE file for users and a ChangeLog for developers.

Perl is doing this wonderfully, I think. The various Changes* files are useful for the porters while the end-user gets a polished perldelta that is articulate, pleasant to read and always contains some additional bits of interest. The perldeltas are one of the things I always keep looking forward to when it comes to new Perl releases (I wonder whether there'll be a perldelta6).

perldelta6

chromatic on 2003-05-13T16:18:14

Strangely, perldelta6 was written before the code!