[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: Wed, 10 Jan 2018 00:22:04 -0800
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.5.0

Richard Stallman wrote:
Description and explanation are two different issues.  Please don't
treat them as the same -- if you do that, we are miscommunicating.

I'm afraid that this miscommunication is endemic to the coding standards, which lump description and explanation together. For example, "Change Log Concepts" currently starts like this (*emphasis* added):

"You can think of the change log as a conceptual “undo list” which *explains* how earlier versions were different from the current version. People can see the current version; they don’t need the change log to tell them what is in it. What they want from a change log is a clear *explanation* of how the earlier version differed. Each entry in a change log *describes* either an individual change or the smallest batch of changes that belong together ..."

The above text uses "explains", "explanation", and "description" for the same thing, namely the change log entry. It is not at all clear from this text that the example change that I gave needs a description and not an explanation.

More generally, if a fact is obvious from the diff listing, the fact needn't appear in the change log entry (and this is true regardless of whether the fact is described or explained). People who are curious about the fact can look at the diff listing and easily figure it out.

reply via email to

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