Re: git history tracking across renames (and emacs support) (Was: The name gnus-cloud.el)

[Paul Eggert]

Eli Zaretskii wrote:

> If you are looking for a specific change in a specific function, then
> ChangeLog style is exactly what you want.  If you are looking for
> something else, why would you look at the log messages at all, instead
> of using VCS commands related to history and forensics?

Because I am looking for *why* the code is the way it is, and ChangeLog entries 
that emphasize function names are typically not that helpful.

For example, I'm currently working on a Coreutils patch so that "mv a b c 
d/e/f/g/" will traverse the directories in d/e/f/g/ just once instead of three 
times (once each for "a", "b", and "c"), thus reducing an O(N**2) to an O(N) 
algorithm. In writing this patch I needed to answer the question, "Why does 
Coreutils currently insist on traversing d/e/f/g/ once for each source file, 
instead of just once for all the source files?" One cannot answer this question 
from the text of Coreutils' ChangeLog entries, even though these entries are 
reasonably well-written using the approved GNU style.

In contrast, the problem "I am looking for a specific change in a specific 
function" is not a big deal, as it is so easily addressed by "git blame" etc. 
that it's not worth the maintenance hassle of writing and maintaining and 
reading commit messages that laboriously list every function that's affected by 
every patch.

I'm not saying that commit messages should *never* mention file or function 
names; far from it. Just that our current style emphasizes them too much, and 
that we'd be better off spending our limited resources on commit messages that 
emphasize motivation instead of enumerating trivia.

>    . the first priority should be to leave the explanation as comments
>      in the code, if that is feasible, because then the commit explains
>      itself, and the information is also available during simple code
>      reading unrelated to VCS history searching;

Yes, that is preferable if it makes sense in the new code. However, it often 
doesn't make sense. For example, when deleting a file one typically does not 
want to leave a message behind where the file used to be, saying "this file was 
deleted", as that would just slow down later maintainers who normally shouldn't 
be burdened with the detritus of older versions.

>    . if the change was discussed in some public forum, include the
>      pointer to that discussion in the log message (bug number is a
>      special case of this, but it's not the only one)

Very good advice.