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