[PATCH] Documentation/submitting-patches: Add blurb about backtraces in commit messages

[Borislav Petkov]

On Mon, Dec 21, 2020 at 09:54:25AM -0700, Jonathan Corbet wrote:
> Given that there was indeed a lack of bikeshedding, I just went ahead
> and applied this to docs-next; will ship it Linusward in the near
> future.

Cool.

Although I betcha that is because of the impending holiday season. I
think I should just use that moment to sneak in more stuff stealthily
and when everyone awakes from their drunken and food stupor, it'll all
be there! Tadaa!

:-)))

Ok, here's the next one which I think, is also, not really controversial.

Thx.

---
From: Borislav Petkov <bp@xxxxxxx>
Date: Tue, 22 Dec 2020 13:58:22 +0100

Document that backtraces in commit messages should be trimmed down to
the useful information only.

This has been carved out from a tip subsystem handbook patchset by
Thomas Gleixner:

  https://lkml.kernel.org/r/20181107171010.421878737@xxxxxxxxxxxxx

and incorporates follow-on comments.

Signed-off-by: Borislav Petkov <bp@xxxxxxx>
---
 Documentation/process/submitting-patches.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 5ba54120bef7..0ffb21366381 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -679,6 +679,26 @@ generates appropriate diffstats by default.)
 See more details on the proper patch format in the following
 references.
 
+Backtraces in commit mesages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.29.2


-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette