What do we want from the Changelog?

[Jeroen van Meeuwen (Kolab Systems)]

Hi there,

after my little screw-up not updating doc/changes.html, which has to 
happen manually, we're now in the realm of fixing this once and for all.

We have the following sources for what changed:

  - git commit logs,
  - bugzilla entries,

Sometimes, fixes are applied after one of our developers finds it (i.e. 
only occurs in git commit log) and sometimes a post to a mailing list 
triggers someone to fix one or the other thing.

Obviously, the most complete changelog is the git commit log. 
Distilling this log in some sort of a readable format is perfectly 
doable;

  [user at system cyrus-imapd.git/] $ (GIT_DIR=.git git log $(git tag -l | 
grep -E "^cyrus-imapd-[0-9]+\.[0-9]+\.[0-9]+$" | grep -B 1 
$(PACKAGE)-$(VERSION) | head -n 1)..$(PACKAGE)-$(VERSION) > 
.changelog.tmp && mv .changelog.tmp ChangeLog; rm -f .changelog.tmp) || 
(touch ChangeLog; echo 'git directory not found: installing possibly 
empty changelog.' >&2)

The list of bugs closed for a certain milestone is easily created as 
well:

   http://www.cyrusimap.org/mediawiki/index.php/Bugs_Resolved_in_2.4.14

I, personally, am in favour of using these lists of things as they are 
(maybe we can enhance the formatting a little but), but adding Release 
Notes to a release should anything need a little bit of text to 
accompany the change.

Today, however, there's a doc/changes.html which needs to be updated as 
well - manually. The latter is where today's confusion comes from, 
really. I had failed to update that document (it wasn't listed in the 
things to do for a release[1]).

Any thoughts/comments/gripes?

Kind regards,

Jeroen van Meeuwen

[1] 
http://www.cyrusimap.org/mediawiki/index.php/Release_Processes_and_Tasks

-- 
Systems Architect, Kolab Systems AG

e: vanmeeuwen at kolabsys.com
m: +44 74 2516 3817
w: http://www.kolabsys.com

pgp: 9342 BF08