Re: [PATCH] gnu: Fix load-extension path in packaging of guile-ncurses.

[Tobias Geerinckx-Rice]

John, Danny,

[Any exasperation is due only to the sustained level of FUD I encounter
about the Guix/GNU changelog format, and not aimed at John.]

On 20/12/16 12:03, John Darrington wrote:
> Sure (I would like to see a convention where such explanations are 
> put in the commit messaage, but I have previously been outvoted on 
> that issue).

I don't think so.

1. What was ‘outvoted’ (with solid argumentation) was hiding comments
documenting code itself in commit messages, when they would do more
good as, well, comments.

2. The Guix commit log has plenty of concise explanations for why code
was *changed*. I See 64b5e41 for a random example. If that guy can get
away with it...

Most People™ badly overdo #2 when they should do #1 (consider the
average *Hub pull request). The opposite is less common.

> On Wed, Dec 21, 2016 at 09:36:56AM +0100, Danny Milosavljevic wrote:
>> No, please don't put explanations into the commit message. But do 
>> put them into the source code as a comment.

I'd just finished writing the exact same e-mail as Danny — almost to the
sentence — when that arrived. So... it must be right! :-)

> That approach can work sometimes, but more often it is a 
> non-starter.

[Examples paraphrased for length:]
> 1. ;; This variable used to be called "bar" but we changed it
> 2. ;; There used to be some code here but we deleted it
> 3. A new variable was introduced in places thoughout the code
> 4. ;; Fred typed 'xyz' when he ought to have put 'abc'

Sorry, but the first three examples are silly. :-)

Deliberately silly, I'm sure, but still these are strawmen that no-one
proposed. On the contrary: examples 1 to 3 are exactly what the current
commit log documents with tedious precision.

That leaves bugfixes.

If the bug is waiting to happen again (and again...), putting a warning
to future readers in a comment might be appropriate. No-one will spot it
in a commit message. (Of course, re-writing the misleading/dangerous
code would be the best solution.)

If the fix is trivial, as in this example, the diff usually speaks for
itself. In all other cases, a short note in the commit message is fine.
This seems to be standard policy for CVEs. So I really don't understand
your complaint.

> But nobody except me will care about bugs in the function which have
> been fixed.

Exactly! In this patch, you're replacing buggy (?) code with shiny code.
That shouldn't take more than ~50 characters to note.

> On Wed, Dec 21, 2016 at 09:36:56AM +0100, Danny Milosavljevic wrote:
>> I'm also working on other projects, some of which do what you 
>> propose. What I often end up having to do there is do git blame, 
>> then git log for each line, in order to find out why the source 
>> code does what it does. Let's not do that here.

+11, unfortunately from experience.

> That is what git blame is for.  Be thankful for it!

No and God no.

That is exactly what ‘git blame’ is not for.

Code itself should be documented in-line. Not in a commit log meant for
documenting changes, that breaks as soon as someone hits C-M-q.

> I hope this explains why putting history in comments is harmful.

It does! But this is not something anyone here suggested.

> Having it in the commit message would certainly have avoided me 
> having to explain the situation to Mark too.

Perhaps. I doubt it. I can't speak for Mark, but most confusion
seemed to stem from the commit message's accuracy, not its length.

But yes, it could have been longer — and a comment :-)

Kind regards,

T G-R

PS: On 21/12/16 10:56, John Darrington wrote:
> Hi Danny,
> 
> A small request: Can you please fold the text of your email to ~80 
> characters.  It's very hard to read otherwise.

FWIW, your replies are equally hard to read (and even harder to reply
to) because of the unconventional indentation. It certainly confuses
Thunderbird, which is easily confused.

signature.asc
Description: OpenPGP digital signature