[PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[Bjorn Helgaas]

Clarify the convention for commit references in changelogs so it matches
what checkpatch suggests; see d311cd44545f ("checkpatch: add test for
commit id formatting style in commit log").

I chose a different example to make the ("") around the description more
obvious.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
---
 Documentation/SubmittingPatches |   33 ++++++++++++---------------------
 1 file changed, 12 insertions(+), 21 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index b03a832..e1063b8 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -168,27 +168,18 @@ resources.  In addition to giving a URL to a mailing list archive or
 bug, summarize the relevant points of the discussion that led to the
 patch as submitted.
 
-If you want to refer to a specific commit, don't just refer to the
-SHA-1 ID of the commit. Please also include the oneline summary of
-the commit, to make it easier for reviewers to know what it is about.
-Example:
-
-	Commit e21d2170f36602ae2708 ("video: remove unnecessary
-	platform_set_drvdata()") removed the unnecessary
-	platform_set_drvdata(), but left the variable "dev" unused,
-	delete it.
-
-You should also be sure to use at least the first twelve characters of the
-SHA-1 ID.  The kernel repository holds a *lot* of objects, making
-collisions with shorter IDs a real possibility.  Bear in mind that, even if
-there is no collision with your six-character ID now, that condition may
-change five years from now.
-
-If your patch fixes a bug in a specific commit, e.g. you found an issue using
-git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
-SHA-1 ID, and the one line summary.  For example:
-
-	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
+When referring to a specific commit, please include both the first 12
+characters of the SHA-1 ID and the one-line summary to make it easier for
+reviewers to know what it is about.  For example:
+
+	Commit 523c5b89640e ("i2c: Remove support for legacy PM") removed
+	the PM ops from the bus type ...
+
+If your patch fixes a bug in a specific commit, e.g., you found an issue
+using git-bisect, please use the 'Fixes:' tag, again with the first 12
+characters of the SHA-1 ID and the one-line summary.  For example:
+
+	Fixes: 523c5b89640e ("i2c: Remove support for legacy PM")
 
 The following git-config settings can be used to add a pretty format for
 outputting the above style in the git log or git show commands

Re: [PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[Joe Perches]

On Thu, 2015-05-21 at 10:59 -0500, Bjorn Helgaas wrote:
> Clarify the convention for commit references in changelogs so it matches
> what checkpatch suggests; see d311cd44545f ("checkpatch: add test for
> commit id formatting style in commit log").
> 
> I chose a different example to make the ("") around the description more
> obvious.
[]
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
[]
> @@ -168,27 +168,18 @@ resources.  In addition to giving a URL to a mailing list archive or
[]
> +When referring to a specific commit, please include both the first 12

maybe

When referring to a specific commit, please include both 12 or more
or "at least 12" or " a minimum of 12".

> +characters of the SHA-1 ID and the one-line summary to make it easier for
> +reviewers to know what it is about.  For example:
> +
> +	Commit 523c5b89640e ("i2c: Remove support for legacy PM") removed
> +	the PM ops from the bus type ...
> +
> +If your patch fixes a bug in a specific commit, e.g., you found an issue
> +using git-bisect, please use the 'Fixes:' tag, again with the first 12

here too

> +characters of the SHA-1 ID and the one-line summary.  For example:
> +
> +	Fixes: 523c5b89640e ("i2c: Remove support for legacy PM")
>  
>  The following git-config settings can be used to add a pretty format for
>  outputting the above style in the git log or git show commands
> 

Re: [PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[Bjorn Helgaas]

On Thu, May 21, 2015 at 11:19 AM, Joe Perches <joe@perches.com> wrote:
> On Thu, 2015-05-21 at 10:59 -0500, Bjorn Helgaas wrote:
>> Clarify the convention for commit references in changelogs so it matches
>> what checkpatch suggests; see d311cd44545f ("checkpatch: add test for
>> commit id formatting style in commit log").
>>
>> I chose a different example to make the ("") around the description more
>> obvious.
> []
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> []
>> @@ -168,27 +168,18 @@ resources.  In addition to giving a URL to a mailing list archive or
> []
>> +When referring to a specific commit, please include both the first 12
>
> maybe
>
> When referring to a specific commit, please include both 12 or more
> or "at least 12" or " a minimum of 12".

OK.  There's value in brevity.  I was trying to avoid the "if 12 is
good, 40 must be better" idea, because 40-char SHA-1s make changelogs
ugly and hard to read.

My git-fu isn't awesome (git log --oneline --abbrev-commit --abbrev=10
| cut -f1 -d" " | grep ...........), but I *think* we have three git
SHA-1s so far that aren't unique in 10 characters (8b82547e338/e
3ee50141858/b a7aa92d1b49/a), and everything is still unique in 11 or
12-char SHA1s.

Bjorn

Re: [PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[Joe Perches]

On Thu, 2015-05-21 at 11:44 -0500, Bjorn Helgaas wrote:
> On Thu, May 21, 2015 at 11:19 AM, Joe Perches <joe@perches.com> wrote:
> > On Thu, 2015-05-21 at 10:59 -0500, Bjorn Helgaas wrote:
> >> Clarify the convention for commit references in changelogs so it matches
> >> what checkpatch suggests; see d311cd44545f ("checkpatch: add test for
> >> commit id formatting style in commit log").
> >>
> >> I chose a different example to make the ("") around the description more
> >> obvious.
> > []
> >> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > []
> >> @@ -168,27 +168,18 @@ resources.  In addition to giving a URL to a mailing list archive or
> > []
> >> +When referring to a specific commit, please include both the first 12
> >
> > maybe
> >
> > When referring to a specific commit, please include both 12 or more
> > or "at least 12" or " a minimum of 12".
> 
> OK.  There's value in brevity.  I was trying to avoid the "if 12 is
> good, 40 must be better" idea, because 40-char SHA-1s make changelogs
> ugly and hard to read.

completely agree.

> My git-fu isn't awesome

Yeah, mine either.

>  (git log --oneline --abbrev-commit --abbrev=10
> | cut -f1 -d" " | grep ...........), but I *think* we have three git
> SHA-1s so far that aren't unique in 10 characters (8b82547e338/e
> 3ee50141858/b a7aa92d1b49/a), and everything is still unique in 11 or
> 12-char SHA1s.

Josh's seems to be strong though.

http://blog.cuviper.com/2013/11/10/how-short-can-git-abbreviate/

12 should be safe for a little while longer.

Re: [PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[Josh Stone]

On 05/21/2015 10:04 AM, Joe Perches wrote:
> On Thu, 2015-05-21 at 11:44 -0500, Bjorn Helgaas wrote:
>> My git-fu isn't awesome
> 
> Yeah, mine either.
> 
>>  (git log --oneline --abbrev-commit --abbrev=10
>> | cut -f1 -d" " | grep ...........), but I *think* we have three git
>> SHA-1s so far that aren't unique in 10 characters (8b82547e338/e
>> 3ee50141858/b a7aa92d1b49/a), and everything is still unique in 11 or
>> 12-char SHA1s.
> 
> Josh's seems to be strong though.

Thanks. :)

> http://blog.cuviper.com/2013/11/10/how-short-can-git-abbreviate/
> 
> 12 should be safe for a little while longer.

Yeah.  For a clean checkout of linux.git, my script says:

$ git rev-parse HEAD
1113cdfe7d2c1fe08b64caa3affe19260e66dd95
$ git-unique-abbrev
4148865 objects
 4: 4148865 / 65536
 5: 4069048 / 948597
 6: 908685 / 435663
 7: 63915 / 31866
 8: 4145 / 2072
 9: 290 / 145
10: 24 / 12
11: 4 / 2
12: 0 / 0
d597639e2036f04f0226761e2d818b31f2db7820 tree 541
d597639e203a100156501df8a0756fd09573e2de tree 1612
ef91b6e893a00d903400f8e1303efc4d52b710af blob 4826
ef91b6e893afc4c4ca488453ea9f19ced5fa5861 blob 12981

I added "git cat-file --batch-check" on the final list of objects.
Anyway, just one new 11-char collision since I wrote that blog post.

I also have a bigger linux repo tracking many more remotes -- with
8344399 objects, this collides at 11-chars in 10 objects, 5 prefixes,
yet 12 is still clean.

Getting closer though...

Re: [PATCH] Docs: SubmittingPatches: Clarify convention for git commit references

[Jonathan Corbet]

On Thu, 21 May 2015 10:59:54 -0500
Bjorn Helgaas <bhelgaas@google.com> wrote:

> Clarify the convention for commit references in changelogs so it matches
> what checkpatch suggests; see d311cd44545f ("checkpatch: add test for
> commit id formatting style in commit log").
> 
> I chose a different example to make the ("") around the description more
> obvious.

In general the change is fine, and I agree with the change in example.
You took out the reasons for use of 12 characters, though, and I'd rather
not do that.  People like to know why a particular practice makes
sense...  Can I get a version that preserves that text?

Thanks,

jon