[PATCH] clean up confusing suggestion for commit references

[PATCH] clean up confusing suggestion for commit references

[Heiko Voigt]

The description for referencing commits looks as if it is contradicting
the example, since it is itself enclosed in double quotes. Lets use
single quotes around the description and include the double quotes in
the description so it matches the example.
---
Sorry for opening this up again but I just looked up the format and was
like: "Umm, which one is now the correct one..."

For this makes more sense. What do others think?

Cheers Heiko

 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 08352de..692f4ce 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -122,7 +122,7 @@ 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)",
+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)
-- 
2.10.0.645.g54f1e86

Re: [PATCH] clean up confusing suggestion for commit references

[Jeff King]

On Fri, Oct 07, 2016 at 11:56:38AM +0200, Heiko Voigt wrote:

> The description for referencing commits looks as if it is contradicting
> the example, since it is itself enclosed in double quotes. Lets use
> single quotes around the description and include the double quotes in
> the description so it matches the example.
> ---
> Sorry for opening this up again but I just looked up the format and was
> like: "Umm, which one is now the correct one..."
> 
> For this makes more sense. What do others think?

Looking over the threads, I wasn't sure there was consensus[1,2]. So it would
be equally correct to drop the quotes from the example.

I dunno. I am in favor of no-quotes, myself, so maybe I am just
manufacturing dissent in my mind. :)

-Peff

[1] http://public-inbox.org/git/a9731f60-5c30-0bc6-f73a-f7ffb7bd4231@kdbg.org/
[2] http://public-inbox.org/git/20160829183015.2uqnfezekjfa3ott@sigill.intra.peff.net/

Re: [PATCH] clean up confusing suggestion for commit references

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Fri, Oct 07, 2016 at 11:56:38AM +0200, Heiko Voigt wrote:
>
>> The description for referencing commits looks as if it is contradicting
>> the example, since it is itself enclosed in double quotes. Lets use
>> single quotes around the description and include the double quotes in
>> the description so it matches the example.
>> ---
>> Sorry for opening this up again but I just looked up the format and was
>> like: "Umm, which one is now the correct one..."
>> 
>> For this makes more sense. What do others think?
>
> Looking over the threads, I wasn't sure there was consensus[1,2]. So it would
> be equally correct to drop the quotes from the example.
>
> I dunno. I am in favor of no-quotes, myself, so maybe I am just
> manufacturing dissent in my mind. :)

I no longer have preference either way myself, even though I was in
favor of no-quotes simply because I had an alias to produce that
format and was used to it.

Re: [PATCH] clean up confusing suggestion for commit references

[Jeff King]

On Mon, Oct 10, 2016 at 11:24:01AM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > On Fri, Oct 07, 2016 at 11:56:38AM +0200, Heiko Voigt wrote:
> >
> >> The description for referencing commits looks as if it is contradicting
> >> the example, since it is itself enclosed in double quotes. Lets use
> >> single quotes around the description and include the double quotes in
> >> the description so it matches the example.
> >> ---
> >> Sorry for opening this up again but I just looked up the format and was
> >> like: "Umm, which one is now the correct one..."
> >> 
> >> For this makes more sense. What do others think?
> >
> > Looking over the threads, I wasn't sure there was consensus[1,2]. So it would
> > be equally correct to drop the quotes from the example.
> >
> > I dunno. I am in favor of no-quotes, myself, so maybe I am just
> > manufacturing dissent in my mind. :)
> 
> I no longer have preference either way myself, even though I was in
> favor of no-quotes simply because I had an alias to produce that
> format and was used to it.

I'll admit that I don't care _that_ much and am happy to leave it up to
individual authors, as long as nobody quotes SubmittingPatches at me as
some kind of gospel when I use the no-quotes form.

-Peff

Re: [PATCH] clean up confusing suggestion for commit references

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Mon, Oct 10, 2016 at 11:24:01AM -0700, Junio C Hamano wrote:
>
>> I no longer have preference either way myself, even though I was in
>> favor of no-quotes simply because I had an alias to produce that
>> format and was used to it.
>
> I'll admit that I don't care _that_ much and am happy to leave it up to
> individual authors, as long as nobody quotes SubmittingPatches at me as
> some kind of gospel when I use the no-quotes form.

;-).  

I just do not want to hear "gitk (or was it git-gui) produces quoted
form, why are you recommending no-quoted form in SubmittingPatches?"

I'd say "use common sense; sometimes it is less confusing to read
without quotes and it is perfectly OK to do so if that is the case".

Re: [PATCH] clean up confusing suggestion for commit references

[Heiko Voigt]

On Mon, Oct 10, 2016 at 12:14:14PM -0700, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> > On Mon, Oct 10, 2016 at 11:24:01AM -0700, Junio C Hamano wrote:
> >
> >> I no longer have preference either way myself, even though I was in
> >> favor of no-quotes simply because I had an alias to produce that
> >> format and was used to it.
> >
> > I'll admit that I don't care _that_ much and am happy to leave it up to
> > individual authors, as long as nobody quotes SubmittingPatches at me as
> > some kind of gospel when I use the no-quotes form.
> 
> ;-).  
> 
> I just do not want to hear "gitk (or was it git-gui) produces quoted
> form, why are you recommending no-quoted form in SubmittingPatches?"
> 
> I'd say "use common sense; sometimes it is less confusing to read
> without quotes and it is perfectly OK to do so if that is the case".

I do not care about which format it should be either. I just wanted to
be clear about whatever should be used. Since it seems we will allow
both, I am also fine with leaving the description as it is ;-)

Cheers Heiko

Re: [PATCH] clean up confusing suggestion for commit references

[Junio C Hamano]

Heiko Voigt <hvoigt@hvoigt.net> writes:

>  If you want to reference a previous commit in the history of a stable
> -branch, use the format "abbreviated sha1 (subject, date)",
> +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)

As long as the "like this" example is there close to the sentence
"use the format ...", I do not think it matters either way in
practice, but I think this change is adding unnecessary confusion.

Both the 'subject' and 'date' on that line are meant to be
placeholders, so where you see subject, you replace it "with the
subject enclosed in a pair of double-quotes" as the next line says.
But then you would end up with:

     Commit f86a374 (""pack-bitmap.c: fix a memleak"", 2015-03-30)

which is not what we want to see.