linux-kernel - [PATCH] docs: git SHA prefixes are for humans

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20241216012743.work.705-kees@kernel.org>
Date: Sun, 15 Dec 2024 17:27:47 -0800
From: Kees Cook <kees@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Kees Cook <kees@...nel.org>,
	Linus Torvalds <torvalds@...ux-foundation.org>,
	Geert Uytterhoeven <geert+renesas@...der.be>,
	Thorsten Leemhuis <linux@...mhuis.info>,
	regressions@...ts.linux.dev,
	workflows@...r.kernel.org,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	linux-hardening@...r.kernel.org
Subject: [PATCH] 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.

Suggested-by: Linus Torvalds <torvalds@...ux-foundation.org>
Link: https://lore.kernel.org/all/CAHk-=wiwAz3UgPOWK3RdGXDnTRHcwVbxpuxCQt_0SoAJC-oGXQ@mail.gmail.com [1]
Signed-off-by: Kees Cook <kees@...nel.org>
---
Cc: Jonathan Corbet <corbet@....net>
Cc: Geert Uytterhoeven <geert+renesas@...der.be>
Cc: Thorsten Leemhuis <linux@...mhuis.info>
Cc: regressions@...ts.linux.dev
Cc: workflows@...r.kernel.org
Cc: linux-doc@...r.kernel.org
---
 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(-)

diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
index 1f5ab49c48a4..a0e8715c6cd3 100644
--- a/Documentation/process/handling-regressions.rst
+++ b/Documentation/process/handling-regressions.rst
@@ -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::
diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
index e374b67b3277..658b489705be 100644
--- a/Documentation/process/maintainer-tip.rst
+++ b/Documentation/process/maintainer-tip.rst
@@ -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@...l>
 
    The latter puts the information about the patch into the focus and
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 1518bd57adab..efd4fb1109e9 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -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
-- 
2.34.1