gEDA-dev: Thoughts on ChangeLog vs. NEWS

[Peter TB Brett]

Hi folks,

Recently some discussion has taken place regarding what ChangeLog and NEWS are 
for.  As you know, both are mandated by the GNU packaging style guidelines.

For most GNU projects, ChangeLog is generated by cvs2cl.pl (or similar for VC 
systems other than CVS), and NEWS is a hand-maintained 'quick reference' 
document for changes, with headings for versions.

The current gEDA ChangeLog file is trying to fulfil both roles: a detailed 
description of changes committed to CVS as well as a good way of working out 
what's changed in each release.

Unfortunately, it's not really succeeding at either.  Because people are 
adding detailed commit descriptions to ChangeLog, they're often not bothering 
to input sufficiently descriptive CVS log messages, which breaks 'cvs log' 
and makes working out what changed when somewhat tricky, while ChangeLog is 
more or less useless when trying to quickly check the changes that have been 
made recently.

Illustrating my point, ideally NEWS should contain lines looking a bit like:



 - Fixed bug #348273: Noblinator not frobnicating correctly



While a more detailed commit message in ChangeLog would look like:



2006-10-18 21:29:00 peter-b

  Fix bug #348273.  Check correctly for NULL pointers in frobnicate(), and add
     memory allocation error handling more gracefully in new_noblinator().

     foo/frobnicate.c (1.2), foo/bar/nobler.c (1.234)


This would combine several advantages: more concise NEWS for people who want 
concise explanations of what's changed, and a more useful ChangeLog and 'cvs 
log' because people will be encouraged to write explanatory log messages.

Cheers,

Peter

-- 
Fisher Society committee                    http://tinyurl.com/o39w2
CUSBC novices, match and league secretary   http://tinyurl.com/mwrc9
CU Spaceflight                              http://tinyurl.com/ognu2

v3sw6YChw7$ln3pr6$ck3ma8u7+Lw3+2m0l7Ci6e4+8t4Gb8en6g6Pa2Xs5Mr4p4
  hackerkey.com                                  peter-b.co.uk
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.seul.org/pipermail/geda-dev/attachments/20061018/8817ca1f/attachment.pgp