Re: [PATCH] Documentation/SubmittingPatches: add quotes to advised commit reference

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 26, 2016, 22:42 UTC
Message-ID: <xmqqk2f3duf2.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160826222714.31459-1-sbeller@google.com>

Stefan Beller <sbeller@google.com> writes:

Show 18 quoted lines

> Junio finds it is easier to read text when the commit subject is quoted.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  Documentation/SubmittingPatches | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 500230c..a591229 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -123,7 +123,7 @@ archive, summarize the relevant points of the discussion.
>  
>  If you want to reference a previous commit in the history of a stable
>  branch use the format "abbreviated sha1 (subject, date)". So for example
> -like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
> +like this: "Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
>  noticed [...]".

Thanks, but it is not sufficient as you would not see the need for quoting without the example.

My preference is not a main deciding factor in this case anyway. A more important reason why it makes sense to quote (aside from the fact that it makes more sense when reading) is because we already have a tool support for that.

Perhaps something like this instead?

-- >8 --
From: Beat Bolli <dev+git@drbeat.li>
Subject: SubmittingPatches: use gitk's "Copy commit summary" format
Date: Fri, 26 Aug 2016 18:59:01 +0200

Update the suggestion in 175d38ca ("SubmittingPatches: document how to reference previous commits", 2016-07-28) on the format to refer to a commit to match what gitk has been giving since last year with its "Copy commit summary" command; also mention this as one of the ways to obtain a commit reference in this format.

Signed-off-by: Beat Bolli <dev+git@drbeat.li>
---
 Documentation/SubmittingPatches | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 500230c..15adb86 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -122,9 +122,14 @@ without external resources. Instead of giving a URL to a mailing list
 archive, summarize the relevant points of the discussion.
 
 If you want to reference a previous commit in the history of a stable
-branch use the format "abbreviated sha1 (subject, date)". So for example
-like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
-noticed [...]".
+branch, use the format "abbreviated sha1 (subject, date)",
+with the subject enclosed in a pair of double-quotes, like this:
+
+    Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
+    noticed that ...
+
+The "Copy commit summary" command of gitk can be used to obtain this
+format.
 
 
 (3) Generate your patch using Git tools out of your commits.