From nobody Mon Feb 9 06:19:20 2026 Received: from metis.whiteo.stw.pengutronix.de (metis.whiteo.stw.pengutronix.de [185.203.201.7]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DE4A01A83FE for ; Fri, 20 Dec 2024 09:09:52 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=185.203.201.7 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734685794; cv=none; b=MxcCyjVWf41Zis1KezzpxJAfyt3VcvvXiQ0pQeCj9+U/1Aig1Ol1wbekyGew8RA+fXLCM+R8l759Q2rH+ZykZjTB7NIpprsQmt+j2vldDz26Z87nc04FNJvCZLrbo72WnaE8221k3nhFzQMr1MzvbBdquRafLQCySKm5Dl5Ie/Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734685794; c=relaxed/simple; bh=8xR4PZzqOumB/ZRcnnAflNpmwuMlSHUJCOTF/duVoQg=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=diimMAPNJ2wQ5XJGim9I3psO50OTYg+H/sFFAHoL6xOU5mIQIB7OVircNDfESpKK5hBlHtifpswx9qxD74hRiiIRXlQf3sWAKKkRDT6f1NWoXJkj8PlblVSEuT8vVrzZzTIvZDZSg6Gqf/4XL7rcNm/cD/rh5ZNV55U8JUq6qmw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=pengutronix.de; spf=pass smtp.mailfrom=pengutronix.de; arc=none smtp.client-ip=185.203.201.7 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=pengutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pengutronix.de Received: from drehscheibe.grey.stw.pengutronix.de ([2a0a:edc0:0:c01:1d::a2]) by metis.whiteo.stw.pengutronix.de with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tOZ10-0001DX-CS; Fri, 20 Dec 2024 10:09:46 +0100 Received: from dude05.red.stw.pengutronix.de ([2a0a:edc0:0:1101:1d::54]) by drehscheibe.grey.stw.pengutronix.de with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1tOZ0z-004LrB-0k; Fri, 20 Dec 2024 10:09:46 +0100 Received: from localhost ([::1] helo=dude05.red.stw.pengutronix.de) by dude05.red.stw.pengutronix.de with esmtp (Exim 4.96) (envelope-from ) id 1tOZ0z-00HILv-32; Fri, 20 Dec 2024 10:09:45 +0100 From: Ahmad Fatoum Date: Fri, 20 Dec 2024 10:09:34 +0100 Subject: [PATCH RFC 1/2] docs: process: submitting-patches: split canonical patch format section Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20241220-submitting-patches-imperative-v1-1-ee874c1859b3@pengutronix.de> References: <20241220-submitting-patches-imperative-v1-0-ee874c1859b3@pengutronix.de> In-Reply-To: <20241220-submitting-patches-imperative-v1-0-ee874c1859b3@pengutronix.de> To: Jonathan Corbet Cc: workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Borislav Petkov , Rob Herring , Frank Li , kernel@pengutronix.de, Ahmad Fatoum X-Mailer: b4 0.14.2 X-SA-Exim-Connect-IP: 2a0a:edc0:0:c01:1d::a2 X-SA-Exim-Mail-From: a.fatoum@pengutronix.de X-SA-Exim-Scanned: No (on metis.whiteo.stw.pengutronix.de); SAEximRunCond expanded to false X-PTX-Original-Recipient: linux-kernel@vger.kernel.org To make it easier to reference specific parts of the patch format, let's add some headings for different parts. Doing that, it becomes clear that backtraces in commit message is out of place being after Reply-To Headers, so move it next to the commit message body subsubsection. Signed-off-by: Ahmad Fatoum --- Documentation/process/submitting-patches.rst | 56 +++++++++++++++++-------= ---- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/p= rocess/submitting-patches.rst index 1518bd57adab501f7a7cf2fdfb9ac3f3a870766e..1474c84b3ac562f5806d85e8ef5= b6e9d23572e59 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -610,6 +610,9 @@ that, if you have your patches stored in a ``git`` repo= sitory, proper patch formatting can be had with ``git format-patch``. The tools cannot create the necessary text, though, so read the instructions below anyway. =20 +Subject Line +^^^^^^^^^^^^ + The canonical patch subject line is:: =20 Subject: [PATCH 001/123] subsystem: summary phrase @@ -683,6 +686,9 @@ Here are some good example Subjects:: Subject: [PATCH v2] sub/sys: Condensed patch summary Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary =20 +From Line +^^^^^^^^^ + The ``from`` line must be the very first line in the message body, and has the form: =20 @@ -693,6 +699,9 @@ patch in the permanent changelog. If the ``from`` line= is missing, then the ``From:`` line from the email header will be used to determine the patch author in the changelog. =20 +Explanation Body +^^^^^^^^^^^^^^^^ + The explanation body will be committed to the permanent source changelog, so should make sense to a competent reader who has long since forgotten the immediate details of the discussion that might have led to @@ -708,6 +717,31 @@ _all_ of the compile failures; just enough that it is = likely that someone searching for the patch can find it. As in the ``summary phrase``, it is important to be both succinct as well as descriptive. =20 +.. _backtraces: + +Backtraces in commit messages +""""""""""""""""""""""""""""" + +Backtraces help document the call chain leading to a problem. However, +not all backtraces are helpful. For example, early boot call chains are +unique and obvious. Copying the full dmesg output verbatim, however, +adds distracting information like timestamps, module lists, register and +stack dumps. + +Therefore, the most useful backtraces should distill the relevant +information from the dump, which makes it easier to focus on the real +issue. Here is an example of a well-trimmed backtrace:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x00000000000= 00064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +Commentary +^^^^^^^^^^ + The ``---`` marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. =20 @@ -746,28 +780,6 @@ patch:: See more details on the proper patch format in the following references. =20 -.. _backtraces: - -Backtraces in commit messages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Backtraces help document the call chain leading to a problem. However, -not all backtraces are helpful. For example, early boot call chains are -unique and obvious. Copying the full dmesg output verbatim, however, -adds distracting information like timestamps, module lists, register and -stack dumps. - -Therefore, the most useful backtraces should distill the relevant -information from the dump, which makes it easier to focus on the real -issue. Here is an example of a well-trimmed backtrace:: - - unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x00000000000= 00064) - at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) - Call Trace: - mba_wrmsr - update_domains - rdtgroup_mkdir - .. _explicit_in_reply_to: =20 Explicit In-Reply-To headers --=20 2.39.5 From nobody Mon Feb 9 06:19:20 2026 Received: from metis.whiteo.stw.pengutronix.de (metis.whiteo.stw.pengutronix.de [185.203.201.7]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3AE3D1A8417 for ; Fri, 20 Dec 2024 09:10:08 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=185.203.201.7 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734685809; cv=none; b=AGWRNxRU79PfMH98xly6oU35RhX7n4EOf9V98bDaQyfIRUr51UQDod3qWm/KlKRD7jLFcsbErNty2sncMUdWPxGkDxdRILq6Pl6LvnXxxALbB8U/pDSZIvwxwoc10ebHa+R5Zi6tXx4elF8oel/AryZ0Cd1wL6NogJQCnqh7Byo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734685809; c=relaxed/simple; bh=gHiGdDoFkBP7qlbsiA+qG4qxkEBIY0sSiY7ZcKKmu8c=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=ZBuOk9ZkCRiLEvk2LA+nZmXaWJd47xSt5s24x8NJ0V3MwNziO6kpqhCe156svJqwb8kcMno0AI6paj7i76Wxsp+VcUR82i51eChMGB97BdcCvcnHyUZvCRG7DFiCONexlsOs33e6VFdGZz5lmkw41h1C1UbqAYUVhc8VoVmUhZI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=pengutronix.de; spf=pass smtp.mailfrom=pengutronix.de; arc=none smtp.client-ip=185.203.201.7 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=pengutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pengutronix.de Received: from drehscheibe.grey.stw.pengutronix.de ([2a0a:edc0:0:c01:1d::a2]) by metis.whiteo.stw.pengutronix.de with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tOZ10-0001DZ-CS; Fri, 20 Dec 2024 10:09:46 +0100 Received: from dude05.red.stw.pengutronix.de ([2a0a:edc0:0:1101:1d::54]) by drehscheibe.grey.stw.pengutronix.de with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1tOZ0z-004LrC-0l; Fri, 20 Dec 2024 10:09:46 +0100 Received: from localhost ([::1] helo=dude05.red.stw.pengutronix.de) by dude05.red.stw.pengutronix.de with esmtp (Exim 4.96) (envelope-from ) id 1tOZ0z-00HILv-33; Fri, 20 Dec 2024 10:09:45 +0100 From: Ahmad Fatoum Date: Fri, 20 Dec 2024 10:09:35 +0100 Subject: [PATCH RFC 2/2] docs: process: submitting-patches: clarify imperative mood suggestion Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20241220-submitting-patches-imperative-v1-2-ee874c1859b3@pengutronix.de> References: <20241220-submitting-patches-imperative-v1-0-ee874c1859b3@pengutronix.de> In-Reply-To: <20241220-submitting-patches-imperative-v1-0-ee874c1859b3@pengutronix.de> To: Jonathan Corbet Cc: workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Borislav Petkov , Rob Herring , Frank Li , kernel@pengutronix.de, Ahmad Fatoum X-Mailer: b4 0.14.2 X-SA-Exim-Connect-IP: 2a0a:edc0:0:c01:1d::a2 X-SA-Exim-Mail-From: a.fatoum@pengutronix.de X-SA-Exim-Scanned: No (on metis.whiteo.stw.pengutronix.de); SAEximRunCond expanded to false X-PTX-Original-Recipient: linux-kernel@vger.kernel.org While we expect commit message titles to use the imperative mood, it's ok for commit message bodies to first include a blurb describing the background of the patch, before delving into what's being done to address the situation. Make this clearer by adding a clarification after the imperative mood suggestion as well as listing Rob Herring's commit 52bb69be6790 ("dt-bindings: ata: pata-common: Add missing additionalProperties on child nodes") as a good example commit message. Signed-off-by: Ahmad Fatoum --- I liked Rob's commit message, because: - It has multiple subsystem prefixes - Uses imperative mood in the commit message title - Doesn't use it in the commit message body showing that it's not a hard requirement - Is short and gives a succinct background - Explains not only why to do the change, but also why it's ok to do it Admittedly though, a C example may be easier to grok for a general audience. I can search for one if that's preferred (or maybe someone has a suitable commit already they wish to suggest?) --- Documentation/process/submitting-patches.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/p= rocess/submitting-patches.rst index 1474c84b3ac562f5806d85e8ef5b6e9d23572e59..b10534e460aa30f2751208bd1ec= a242841ba5edb 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -96,6 +96,11 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] c= hanged xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour. =20 +The goal of the imperative mood is to make especially commit message +titles (the :ref:`patch_subject_line`) succinct and to the point. +The explanation body should be more detailed and take care to explain +the background motivating the change. (see :ref:`patch_explanation_body`). + 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. @@ -610,6 +615,8 @@ that, if you have your patches stored in a ``git`` repo= sitory, proper patch formatting can be had with ``git format-patch``. The tools cannot create the necessary text, though, so read the instructions below anyway. =20 +.. _patch_subject_line: + Subject Line ^^^^^^^^^^^^ =20 @@ -699,6 +706,8 @@ patch in the permanent changelog. If the ``from`` line= is missing, then the ``From:`` line from the email header will be used to determine the patch author in the changelog. =20 +.. _patch_explanation_body: + Explanation Body ^^^^^^^^^^^^^^^^ =20 @@ -717,6 +726,15 @@ _all_ of the compile failures; just enough that it is = likely that someone searching for the patch can find it. As in the ``summary phrase``, it is important to be both succinct as well as descriptive. =20 +Here is one example of a good commit message:: + + dt-bindings: ata: pata-common: Add missing additionalProperties on child= nodes + + The PATA child node schema is missing constraints to prevent unknown + properties. As none of the users of this common binding extend the child + nodes with additional properties, adding "additionalProperties: false" + here is sufficient. + .. _backtraces: =20 Backtraces in commit messages --=20 2.39.5