doc: update SubmittingPatches about the Fixes tag
Subsystems (2)
PATCH 1/1 doc: update SubmittingPatches about the Fixes tag
From: Jacob Keller <[email protected]>
This patch updates the SubmittingPatches process to include howto about the new 'Fixed' tag to be used when a patch fixes an issue in a previous commit (found by git-bisect for example).
--- Documentation/SubmittingPatches | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-)
Documentation/SubmittingPatches +21 -1
@@ -132,6 +132,20 @@ Example: platform_set_drvdata(), but left the variable "dev" unused, delete it. +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. +Example: + + Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") + +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 + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") 3) Separate your changes.
@@ -443,7 +457,7 @@ person it names. This tag documents that potentially interested parties have been included in the discussion -14) Using Reported-by:, Tested-by:, Reviewed-by: and Suggested-by: +14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: If this patch fixes a problem reported by somebody else, consider adding a Reported-by: tag to credit the reporter for their contribution. Please
@@ -498,6 +512,12 @@ idea was not posted in a public forum. That said, if we diligently credit our idea reporters, they will, hopefully, be inspired to help us again in the future. +A Fixes: tag indicates that the patch fixes an issue in a previous commit. It +is used to make it easy to determine where a bug originated, which can help +review a bug fix. This tag also assists the stable kernel team in determining +which stable kernel versions should receive your fix. This is the preferred +method for indicating a bug fixed by the patch. See #2 above for more details. + 15) The canonical patch format
Signature · 1 line
1.9.0
PATCH 1/1 Documentation/process: hardcoded core.abbrev considered harmful!
Stop recommending that core.abbrev=12 be hardcoded when referring to kernel commits, and instead rely on the git's default abbreviation.
Hardcoding this at "12" was done in8401aa1f5997 ("Documentation/SubmittingPatches: describe the Fixes:
tag", 2014-06-06), back then Linus's git/git@e6c587c733 ("abbrev: auto size the default abbreviation", 2016-09-30) had not yet landed, and the default abbreviation was "7".
At the time linux.git had around 3.5 million objects, so if the auto sizing had been in effect "11" would have been picked. Now "12" is what we pick by default anyway.
More importantly, we'll roll over to "13" at around 16 million objects, which given the growth rate isn't that far off. At that point this documentation will be worse than the default.
Let's just stop doing this. Git versions as of 2.11 released over 2 years ago use the auto-sizing, and it seems like a fair assumption that kernel developers use a fairly recent git version.
---
As an aside I have upcoming git.git patches so you'll be able to set core.abbbrev to e.g. +1 to get "13" now, "14" when it rolls over at ~16 million etc. Maybe that'll be a good fit for projects like linux.git that want more future-proof abbreviated SHAs than most.
Documentation/process/submitting-patches.rst | 2 -- 1 file changed, 2 deletions(-)
Documentation/process/submitting-patches.rst +0 -2
@@ -189,8 +189,6 @@ the SHA-1 ID, and the one line summary. For example:: 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:: - [core] - abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\")
Signature · 1 line
2.20.1.415.g653613c723
Re: [PATCH] Documentation/process: hardcoded core.abbrev considered harmful!
Quoted 2 lines · Ævar Arnfjörð Bjarmason
Stop recommending that core.abbrev=12 be hardcoded when referring to kernel commits, and instead rely on the git's default abbreviation.
Nothing happened to this patch and there was no reply to it as far as I can tell.
This may be sensible for future git versions, but perhaps there should be a different abbrev control added and the kernel should enable that.
Quoted 4 lines
As an aside I have upcoming git.git patches so you'll be able to set core.abbbrev to e.g. +1 to get "13" now, "14" when it rolls over at ~16 million etc. Maybe that'll be a good fit for projects like linux.git that want more future-proof abbreviated SHAs than most.
Will '$ git config --get core.abbrev' return a specific number in that case?
(not +1 and not blank as current if unspecified)
RE: [PATCH] Documentation/process: hardcoded core.abbrev considered harmful!
Quoted 27 lines
-----Original Message-----
From: Joe Perches [mailto:[email protected]]
Sent: Tuesday, January 15, 2019 11:41 AM
To: Ævar Arnfjörð Bjarmason <[email protected]>; Linus Torvalds <torvalds@linux- foundation.org>
Cc: [email protected]; Keller, Jacob E <[email protected]>; Andrew Morton <[email protected]>; Kirsher, Jeffrey T <[email protected]>
Subject: Re: [PATCH]Documentation/process: hardcoded core.abbrev considered harmful!Quoted 2 lines · Ævar Arnfjörð Bjarmason
Stop recommending that core.abbrev=12 be hardcoded when referring to kernel commits, and instead rely on the git's default abbreviation.
Nothing happened to this patch and there was no reply to it as far as I can tell.
This may be sensible for future git versions, but perhaps there should be a different abbrev control added and the kernel should enable that.
Quoted 4 lines
As an aside I have upcoming git.git patches so you'll be able to set core.abbbrev to e.g. +1 to get "13" now, "14" when it rolls over at ~16 million etc. Maybe that'll be a good fit for projects like linux.git that want more future-proof abbreviated SHAs than most.
Quoted 5 lines
Will '$ git config --get core.abbrev' return a specific number in that case?
(not +1 and not blank as current if unspecified)
I wouldn't think so. There might need to be some sort of plumbing command added to obtain this information.
Might be worth pointing that out on the git-devel mailing list.
Thanks,
Jake
Re: [PATCH] Documentation/process: hardcoded core.abbrev considered harmful!
In reply to Ævar Arnfjörð BjarmasonHi all,
Quoted 18 lines · On Thu, 20 Dec 2018 01:01:12 +0100 Ævar Arnfjörð Bjarmason <[email protected]>…
Stop recommending that core.abbrev=12 be hardcoded when referring to kernel commits, and instead rely on the git's default abbreviation.
Hardcoding this at "12" was done in
8401aa1f5997("Documentation/SubmittingPatches: describe the Fixes:
tag", 2014-06-06), back then Linus's git/git@e6c587c733 ("abbrev: auto size the default abbreviation", 2016-09-30) had not yet landed, and the default abbreviation was "7".At the time linux.git had around 3.5 million objects, so if the auto sizing had been in effect "11" would have been picked. Now "12" is what we pick by default anyway.
More importantly, we'll roll over to "13" at around 16 million objects, which given the growth rate isn't that far off. At that point this documentation will be worse than the default.
Quoted 5 lines
Let's just stop doing this. Git versions as of 2.11 released over 2 years ago use the auto-sizing, and it seems like a fair assumption that kernel developers use a fairly recent git version.
Signed-off-by Ævar Arnfjörð Bjarmason <[email protected]>
Since I have been checking Fixes: tags, it has become obvious that some kernel developers have core.abbrev set to 7, 9 or 10 (or maybe they are running very old versions of git). Hopefully this will encourage them to remove that setting (and upgrade).
Can someone (Jon?) please apply this patch?
Signature · 2 lines
Cheers, Stephen Rothwell
Re: [PATCH] Documentation/process: hardcoded core.abbrev considered harmful!
Quoted 24 lines · Stephen Rothwell
Hi all,
Quoted 21 lines · On Thu, 20 Dec 2018 01:01:12 +0100 Ævar Arnfjörð Bjarmason <[email protected]>…
Stop recommending that core.abbrev=12 be hardcoded when referring to kernel commits, and instead rely on the git's default abbreviation.
Hardcoding this at "12" was done in
8401aa1f5997("Documentation/SubmittingPatches: describe the Fixes:
tag", 2014-06-06), back then Linus's git/git@e6c587c733 ("abbrev: auto size the default abbreviation", 2016-09-30) had not yet landed, and the default abbreviation was "7".At the time linux.git had around 3.5 million objects, so if the auto sizing had been in effect "11" would have been picked. Now "12" is what we pick by default anyway.
More importantly, we'll roll over to "13" at around 16 million objects, which given the growth rate isn't that far off. At that point this documentation will be worse than the default.
Let's just stop doing this. Git versions as of 2.11 released over 2 years ago use the auto-sizing, and it seems like a fair assumption that kernel developers use a fairly recent git version.
That might not be a fair assumption. The two systems that I submit patches from have git versions older than 2.11.
-Frank
Quoted 12 lines
Quoted 2 lines
Signed-off-by Ævar Arnfjörð Bjarmason <[email protected]>Acked-by Stephen Rothwell <[email protected]>Since I have been checking Fixes: tags, it has become obvious that some kernel developers have core.abbrev set to 7, 9 or 10 (or maybe they are running very old versions of git). Hopefully this will encourage them to remove that setting (and upgrade).
Can someone (Jon?) please apply this patch?