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

[Eli Zaretskii]

> Cc: address@hidden, address@hidden, address@hidden
> From: Paul Eggert <address@hidden>
> Date: Tue, 2 Jan 2018 18:50:06 -0800
> 
> 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.

I don't think ChangeLog style entries pretend to be the answer to such
questions.  ChangeLog files are supposed to be a concise log of
changes, nothing more, nothing less.

> 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.

I very much doubt that such design-level information can be reasonably
well explained in commit log messages.  It should be a subject for a
relatively long and detailed commentary, i.e. part of the code.  Or,
if a package has an "internals" document, this kind of information
should be there.

> 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. 

When you know the name of the function, the likes of "git annotate"
and "git log -L" might indeed frequently be what you want.
Frequently, but not always: I find ChangeLog's more convenient when I
need to know the date or the Emacs release where some specific change
appeared.  Git tools might be overkill here, and they need non-trivial
startup time before you can search anything.

>  >    . 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.

Deleting a file or deleting some code without a trace is relatively
rare, but indeed this is one situation where comments are sometimes
inadequate, especially if all the change does is remove something (as
opposed to remove something in one place and add/modify another).

>  >    . 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.

I can say from my experience that I almost always find related
discussions around the date of a change, but looking for them is
tedious: we have 2 mailing lists, and until 10 years ago we had 3.  It
takes time to look in all of them, especially since it's not always
evident what search keywords to use.  Having references in the log
message makes this much easier.