docs: git SHA prefixes are for humans
Subsystems (3)
PATCH 1/1 docs: git SHA prefixes are for humans
Clarify that the preferred git SHA abbreviation length for the Fixes tag is 12 characters[1], as the tag is intended for humans (though, yes, it is parsed by machines too). Collision resolution needs to be performed using the parenthetical patch Subject that follows the abbreviated hash.
---
Cc: Jonathan Corbet <[email protected]>
Cc: Geert Uytterhoeven <[email protected]>
Cc: Thorsten Leemhuis <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
--- Documentation/process/handling-regressions.rst | 4 ++-- Documentation/process/maintainer-tip.rst | 4 ++-- Documentation/process/submitting-patches.rst | 6 ++++++ 3 files changed, 10 insertions(+), 4 deletions(-)
Documentation/process/handling-regressions.rst +2 -2
@@ -29,9 +29,9 @@ The important bits (aka "The TL;DR") * For mailed reports, check if the reporter included a line like ``#regzbot introduced: v5.13..v5.14-rc1``. If not, send a reply (with the regressions list in CC) containing a paragraph like the following, which tells regzbot - when the issue started to happen:: + when the issue started to happen, preferably with a full git SHA:: - #regzbot ^introduced: 1f2e3d4c5b6a + #regzbot ^introduced: 1f2e3d4c5b6a1524e886b7f1b8a0c1fc7321cac2 * When forwarding reports from a bug tracker to the regressions list (see above), include a paragraph like the following::
Documentation/process/maintainer-tip.rst +2 -2
@@ -284,7 +284,7 @@ following tag ordering scheme: Commit - abcdef012345678 ("x86/xxx: Replace foo with bar") + ab0123456789 ("x86/xxx: Replace foo with bar") left an unused instance of variable foo around. Remove it.
@@ -295,7 +295,7 @@ following tag ordering scheme: The recent replacement of foo with bar left an unused instance of variable foo around. Remove it. - Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar") + Fixes: ab0123456789 ("x86/xxx: Replace foo with bar") Signed-off-by: J.Dev <j.dev@mail> The latter puts the information about the patch into the focus and
Documentation/process/submitting-patches.rst +6 -0
@@ -163,6 +163,12 @@ An example call:: $ git log -1 --pretty=fixes 54a4f0239f2e Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +Note that the "Fixes" tag, while it does get parsed by machines, is intended +for humans (hence the Subject portion). It is preferred that hashes remain at +12 characters even in the face of prefix collisions. When encountering hash +prefix collisions, tools (and humans) need to resolve such collisions using +the parenthetical patch Subject. + .. _split_changes: Separate your changes
Signature · 1 line
2.34.1
Thorsten Leemhuis
maintainerHi! Thx for picking this up!
Quoted 10 lines · Kees Cook
Clarify that the preferred git SHA abbreviation length for the Fixes tag is 12 characters[1], as the tag is intended for humans (though, yes, it is parsed by machines too). Collision resolution needs to be performed using the parenthetical patch Subject that follows the abbreviated hash. [...]
Documentation/process/handling-regressions.rst +0
-0
Documentation/process/handling-regressions.rst The important bits (aka "The TL;DR") · line 32
Quoted 5 lines
Documentation/process/handling-regressions.rst +1
-1@@ -29,9 +29,9 @@ The important bits (aka "The TL;DR") * For mailed reports, check if the reporter included a line like ``#regzbot introduced: v5.13..v5.14-rc1``. If not, send a reply (with the regressions list in CC) containing a paragraph like the following, which tells regzbot - when the issue started to happen:: + when the issue started to happen, preferably with a full git SHA::
How about "when the issue started to happen using an unique identifier understood by git like the commit-id::"?
Regzbot handles tags, too. And I guess the term "commit-id" is more common and easier to understand for non-developers than "SHA". And in case we ever start using SHA256 sums in the kernel that maybe can just stay as it is.
Documentation/process/maintainer-tip.rst following tag ordering scheme: · line 287
Quoted 12 lines
[...]
Documentation/process/maintainer-tip.rst +1
-1@@ -284,7 +284,7 @@ following tag ordering scheme: Commit - abcdef012345678 ("x86/xxx: Replace foo with bar") + ab0123456789 ("x86/xxx: Replace foo with bar")
Ignore the following side note, I just need to get this off my chest:
Why does that file even mention this and a lot of other stuff how to create a proper patch description at all? We already have two documents that explain this; a third just for one subsystem seems somewhat wrong.
But whatever. :-D
Quoted 6 lines
[...]
Documentation/process/submitting-patches.rst +0
-0
Documentation/process/submitting-patches.rst An example call:: · line 171
Quoted 9 lines
Documentation/process/submitting-patches.rst +6
-0@@ -163,6 +163,12 @@ An example call:: $ git log -1 --pretty=fixes 54a4f0239f2e Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +Note that the "Fixes" tag, while it does get parsed by machines, is intended +for humans (hence the Subject portion). It is preferred that hashes remain at +12 characters even in the face of prefix collisions. When encountering hash +prefix collisions, tools (and humans) need to resolve such collisions using +the parenthetical patch Subject. +
submitting-patches.rst to my understanding and the header of that file is the shorter of two approaches documenting how to contribute patches. So this text should likely go to the longer one, which is Documentation/process/5.Posting.rst. Or both, if we consider this important enough -- but I'd say it's not.
Ciao, Thorsten