[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: git history tracking across renames (and emacs support) (Was: The na

From: Paul Eggert
Subject: Re: git history tracking across renames (and emacs support) (Was: The name gnus-cloud.el)
Date: Tue, 2 Jan 2018 18:50:06 -0800
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.5.0

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]