What do we want from the Changelog?
dave64 at andrew.cmu.edu
Tue Mar 13 10:02:51 EDT 2012
On 03/13/2012 09:43 AM, Rudy Gevaert wrote:
> I have a comment that (in my opinion) fits in this thread.
> I would like to see a good way of pointing out new imapd.conf options.
> Now you have to look at bug reports, changelog, install-upgrade to find
> Sometimes they are not documented even, but that is a different problem.
> Regarding install-upgrade.html, I think that this file is not read by
> default by most sysadmins. E.g. I just look in the changelog. If it
> mentions install-upgrade.html I go look at it.
> (Unless I know there are big changes.)
What I take from this so far is that we have varied requirements:
1) Developers (and sometimes system administrators) want a ChangeLog to
show them exactly which things have changed in the code base.
2) System administrators want to know what will break if they upgrade
from version X to version Y.
3) System administrators want to know about new features. Things like
multi-channel replication that aren't a requirement to set up, but would
be nice to set up if they knew it existed.
Automating the ChangeLog should still perfectly fulfill the first
requirement, so that seems like it's a no-brainer. If it's left to the
developers and release engineer to manually construct a ChangeLog each
time there's a release, things will be forgotten.
The second requirement seems to be best handled by manually updating
file comes with the release tarball, and it's on the website. If you're
a system administrator doing a Cyrus upgrade and you fail to read the
"Upgrading From Previous Versions" document, I can't imagine that you'd
fare much better by reading the ChangeLog.
The third one is where we can probably improve the most, and I'm not
sure what the best way of doing this is. We could add new content to
the website to crow (subtle Cyrus murder joke intended) about new
features, I guess. Anyone else have ideas?
More information about the Cyrus-devel