What do we want from the Changelog?

[Dave McMurtrie]

On 03/13/2012 09:43 AM, Rudy Gevaert wrote:
> Hello,
>
> 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
> them.
>
> 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.

Anything else?

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 
http://cyrusimap.org/docs/cyrus-imapd/2.4.14/install-upgrade.php.  This 
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?

Thanks,

Dave