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

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>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20150521155954.9522.33952.stgit@bhelgaas-glaptop2.roam.corp.google.com>
Date:	Thu, 21 May 2015 10:59:54 -0500
From:	Bjorn Helgaas <bhelgaas@...gle.com>
To:	Jonathan Corbet <corbet@....net>
Cc:	Joe Perches <joe@...ches.com>, linux-kernel@...r.kernel.org,
	linux-doc@...r.kernel.org
Subject: [PATCH] Docs: SubmittingPatches: Clarify convention for git commit
 references

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@...gle.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

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/