linux-kernel - [PATCH RFC 0/2] docs: process: submitting-patches: clarify imperative mood suggestion

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: <20241220-submitting-patches-imperative-v1-0-ee874c1859b3@pengutronix.de>
Date: Fri, 20 Dec 2024 10:09:33 +0100
From: Ahmad Fatoum <a.fatoum@...gutronix.de>
To: Jonathan Corbet <corbet@....net>
Cc: workflows@...r.kernel.org, linux-doc@...r.kernel.org, 
 linux-kernel@...r.kernel.org, Borislav Petkov <bp@...e.de>, 
 Rob Herring <robh@...nel.org>, Frank Li <Frank.li@....com>, 
 kernel@...gutronix.de, Ahmad Fatoum <a.fatoum@...gutronix.de>
Subject: [PATCH RFC 0/2] docs: process: submitting-patches: clarify
 imperative mood suggestion

Many commit message bodies start off with some background information,
before explaining how they address the situation. This can be arguably
easier to follow than having the imperative in the commit message title
be followed directly by another differently worded or more verbose
imperative in the commit message body and then at the end an
", because ..." with an explanation why things were done this way.

Yet, while the documentation talks about use of imperative mood, it does
not fully explain why, which IMO makes it prone to misunderstanding[1][2].

Therefore adapt the documentation to clarify the intent of the imperative
mood and give an example for how a good commit message can look like.

[1]: https://lore.kernel.org/all/f085aa33-f0b7-49e7-bbfc-d3728d3e3e8c@pengutronix.de/#t
[2]: https://lore.kernel.org/all/Z2RzA5S%2Fch1YDdUD@lizhi-Precision-Tower-5810/

---
Ahmad Fatoum (2):
      docs: process: submitting-patches: split canonical patch format section
      docs: process: submitting-patches: clarify imperative mood suggestion

 Documentation/process/submitting-patches.rst | 74 +++++++++++++++++++---------
 1 file changed, 52 insertions(+), 22 deletions(-)
---
base-commit: 78d4f34e2115b517bcbfe7ec0d018bbbb6f9b0b8
change-id: 20241219-submitting-patches-imperative-248413781db1

Best regards,
-- 
Ahmad Fatoum <a.fatoum@...gutronix.de>