[PATCH] doc: update SubmittingPatches about the Fixes tag

[PATCH] doc: update SubmittingPatches about the Fixes tag

[Jeff Kirsher]

From: Jacob Keller <jacob.e.keller@intel.com>

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).

Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Tested-by: Aaron Brown <aaron.f.brown@intel.com>
Signed-off-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
---
 Documentation/SubmittingPatches | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 2a8e89e..7e9abb8 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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
 
-- 
1.9.0

[PATCH] Documentation/process: hardcoded core.abbrev considered harmful!

[Æ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.

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.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---

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(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index c0917107b90a..faf661f58cb1 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -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\")
 
-- 
2.20.1.415.g653613c723

Re: [PATCH] Documentation/process: hardcoded core.abbrev considered harmful!

[Joe Perches]

On Thu, 2018-12-20 at 01:01 +0100, Ævar Arnfjörð Bjarmason wrote:
> 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.

> 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!

[Keller, Jacob E]

> -----Original Message-----
> From: Joe Perches [mailto:golf@perches.com]
> Sent: Tuesday, January 15, 2019 11:41 AM
> To: Ævar Arnfjörð Bjarmason <avarab@gmail.com>; Linus Torvalds <torvalds@linux-
> foundation.org>
> Cc: linux-kernel@vger.kernel.org; Keller, Jacob E <jacob.e.keller@intel.com>; Andrew
> Morton <akpm@linux-foundation.org>; Kirsher, Jeffrey T
> <jeffrey.t.kirsher@intel.com>
> Subject: Re: [PATCH] Documentation/process: hardcoded core.abbrev considered
> harmful!
> 
> On Thu, 2018-12-20 at 01:01 +0100, Ævar Arnfjörð Bjarmason wrote:
> > 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.
> 
> > 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)
> 

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!

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 1584 bytes --]

Hi all,

On Thu, 20 Dec 2018 01:01:12 +0100 Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>
> 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.
> 
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>

Acked-by: Stephen Rothwell <sfr@canb.auug.org.au>

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?
-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] Documentation/process: hardcoded core.abbrev considered harmful!

[Frank Rowand]

On 1/29/19 4:18 PM, Stephen Rothwell wrote:
> Hi all,
> 
> On Thu, 20 Dec 2018 01:01:12 +0100 Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>>
>> 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


>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> 
> Acked-by: Stephen Rothwell <sfr@canb.auug.org.au>
> 
> 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?
>