Date: Fri,  1 Mar 2024 14:46:37 +0100
From: Lukas Bulwahn <lukas.bulwahn@...il.com>
To: Jonathan Corbet <corbet@....net>,
	workflows@...r.kernel.org,
	linux-doc@...r.kernel.org
Cc: kernel-janitors@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Lukas Bulwahn <lukas.bulwahn@...il.com>
Subject: [PATCH 3/3] docs: submitting-patches: move backtraces to patch description

The top-level structure should basically be along the temporal order of
things: Prepare a patch, Post a patch, Respond to review, Send reworked
patches, Be patient before resending.

For that, content from the canonical patch format needs to dissolve into
the pieces along the temporal order.

Move the subsection on backtraces in the canonical patch format into the
'describe your change' section.

As we would like to keep backtraces as a subsection (maintainer-tip.rst
refers to it), let us add another subsection in the 'describe your
change' section and turn the title into imperative form.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@...il.com>
---
 Documentation/process/submitting-patches.rst | 47 +++++++++++---------
 1 file changed, 25 insertions(+), 22 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 37925cacc5cc..584bcd8638ea 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -130,6 +130,9 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
 to do frotz", as if you are giving orders to the codebase to change
 its behaviour.
 
+Refer to URLs and commits in common style
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 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.
@@ -197,6 +200,28 @@ 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")
 
+.. _backtraces:
+
+Distill backtraces
+~~~~~~~~~~~~~~~~~~
+
+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 0x0000000000000064)
+  at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
+  Call Trace:
+  mba_wrmsr
+  update_domains
+  rdtgroup_mkdir
+
 
 Style-check your changes
 ------------------------
@@ -742,28 +767,6 @@ patch::
 See more details on the proper patch format in the following
 references.
 
-.. _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 0x0000000000000064)
-  at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
-  Call Trace:
-  mba_wrmsr
-  update_domains
-  rdtgroup_mkdir
-
 .. _explicit_in_reply_to:
 
 Explicit In-Reply-To headers
-- 
2.43.2

Powered by blists - more mailing lists