ChangeLog entry complexity

[Joseph S. Myers]

On Wed, 27 Mar 2013, David Miller wrote:

> From: "Joseph S. Myers" <joseph@codesourcery.com>
> Date: Wed, 27 Mar 2013 14:26:28 +0000
> 
> > ChangeLog entries provide a useful level of description of changes
> 
> Which can be more effectively reproduced, with the searcher's desired
> level of detail, using the source code control system we use.

If you define machine-parseable conventions for formatting log messages to 
provide the human-level descriptions of the changes to each part of the 
code, then you're not actually saving any effort compared to that for 
writing a sensibly evolved version of ChangeLog entries (i.e. one where 
the "why" is included alongside the "what", and global changes detail 
things at the function / file level only where that's a useful level of 
description for the patch in question).

I think having such fully-defined conventions that allow automatic 
ChangeLog generation would be reasonable, but automatic ChangeLog 
generation itself (with gitlog-to-changelog or similar, including 
processes for corrections to past log entries) would only be effective for 
the goal of source trees always carrying information about what changes 
are in them (when passing through tarballs, different VCSes etc.) if 
things could be configured so that checkouts automatically include the 
automatically updated ChangeLog file (without special client-side 
configuration being needed).  ChangeLog generation only at release time is 
much less satisfactory.

-- 
Joseph S. Myers
joseph@codesourcery.com