What do we want from the Changelog?

[Andrew Morgan]

On Mon, 12 Mar 2012, Jeroen van Meeuwen (Kolab Systems) wrote:

> 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?

Sometimes a new version requires the administrator to take special 
actions.  For example, re-compiling sieve scripts or when an important 
default has changed (allowplaintext, for example).  In the past, I have 
used the changes.html file to find these important changes.

Including those types of warnings and caveats will probably remain a 
manual process.

 	Andy