GNU bug report logs - #73232
[PATCH] Allow vc-diff to suggest a default revision in vc-dir

Previous Next

Full log

Message #20 received at 73232 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: sbaugh <at> janestreet.com, 73232 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: Re: bug#73232: [PATCH] Allow vc-diff to suggest a default revision in
 vc-dir
Date: Sat, 14 Sep 2024 19:13:40 +0300

On 14/09/2024 10:04, Eli Zaretskii wrote:

>> Also I wonder if it's okay to have a multi-paragraph description in the
>> commit message. CONTRIBUTE seems to suggest one paragraph (if any)
>> between the summary and the ChangeLog-style contents, but it doesn't
>> suggest moving any parts of the description to the bug tracker. But IDK,
>> for those who still read the changelog files (instead of using
>> vc-print-root-log) this might be too much for a short change. The
>> detailed description is great, though, so thanks.
> 
> I've modified CONTRIBUTE to not insist on "a paragraph".  (This is
> exactly why I hate to codify stuff that is usually a no-brainer:
> people tend to interpret each word and letter literally, as if they
> were in a legally-binding document, and there's no end to complaints
> and discussions about these unimportant details.)
> 
> My POV is that the description should be as clear and concise as
> possible.  In most cases, there should be a bug report for the issue,
> or some on-list discussion of it, and the gory details should be
> described there, with only a reference left in the log message.  And,
> of course, the important stuff that explains how the code works and
> why it does something non-trivial should be in comments in the code.
> 
> IOW, I consider a long and very detailed description in the log
> message a clear sign that something went wrong in the process: either
> we didn't have the issue discussed in a place that can be referenced,
> or the code needs to be cleaned-up or commented, or something else.
> Git log is NOT the best place to document code changes.

Thanks. So if I understand this right, we're allowed to have multiple 
paragraphs in the commit message's description, but we'd rather not.

Perhaps we'd opt for this approach more often when there is no existing 
bug report.

>> Eli and others, what do you think?
> 
> If you are asking about this bug report, then frankly I don't
> understand the use case: when would a user want to invoke this command
> with point on a directory?

I was asking primarily about the documentation standard, so it's okay if 
you don't have a strong position on this. Thanks anyway.

> Directories are never important items in
> VC-related activities; files are.

IME it's pretty common to invoke vc-root-diff from the vc-dir buffer.

And we also added the capability to call vc-diff from Dired recently.

I don't do this myself often, TBH, but if someone is working in large 
repo, and the project is split into directories along subsystem lines, 
then one might want to make commits limited to subdirectories. Then it 
should be useful to call vc-diff on such a directory first.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.