Re: ChangeLog entry complexity

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Mon, 25 Mar 2013, Eric Wong wrote:

> As others have said, git is fast and powerful.  There is no benefit to
> reading a static ChangeLog when one can run git blame/log with the
> appropriate options to get exactly what you need (and most importantly,
> quickly filter out what one does not want).

Given the messy state of the history converted from CVS (sometimes the 
heuristics to combine separate CVS commits to separate files into a single 
git commit helped, but sometimes they made things worse), in practice the 
ChangeLogs are often a better place to find all the history in one place 
(together with checking the old CVS repository in tricky cases).

> ChangeLog entries also lead to needing extra tools like
> git-merge-changelog instead of just doing a plain cherry-pick/am.

Not having a checked-in ChangeLog leads to on-the-side extra files with 
corrections to bad log messages and author information, information about 
multiple authors where git can only show one, etc. (see 
gitlog-to-changelog --amend).  (I think in principle things such as log 
messages should themselves be versioned objects so you could refer to the 
state of the tree as of a particular commit, which would refer not just to 
the files in the tree and the history of the tree but to the state of the 
log messages etc. in that history.  But I don't know of any version 
control systems that do that.)

I think we *should* move to putting both title lines (as explicitly 
described in the GNU Coding Standards) and rationale at the top of 
ChangeLog entries, in addition to the descriptions of "what" changed, and 
also putting that detailed patch description in the commit messages.  But 
this would require that the detailed description be reviewed for 
formatting and English usage in as much detail as the rest of the patch.  
It would also mean that many patch submissions could have just the 
ChangeLog entry and patch, without anything else above the ChangeLog 
entry, as the entry would show the full rationale.  (Revised submissions 
would still have descriptions of the changes in that particular version 
above the log entry, then the full, possibly amended, rationale in the 
ChangeLog entry.)

I also think that for the problem cases of large global mechanical changes 
it's reasonable to simplify the "what" part of the log just to list files 
changed or not to list them at all (as in the log entries when I moved all 
files to copyright year ranges).

I also think the issue of having lots of separate ChangeLog files for 
changes affecting all architectures should best be addressed by moving 
ports into libc proper after eliminating the remaining ways in which libc 
architectures still put some things in architecture-independent files that 
should be in sysdeps files.  Then it would just be the main ChangeLog and 
those for libidn, localedata, nptl and nptl_db.  Even withing ports, the 
separate ChangeLogs for different architectures were really an artifact of 
CVS ACLs used to control who could commit changes to each port.

-- 
Joseph S. Myers
joseph@codesourcery.com