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

[Jonathan Corbet]

[Digging out from under the pile of mail...]

> 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
> +

So I have some questions, I guess...  How often is a backtrace *in a commit
message* really helpful at all?  The value in problem reports is clear, but
I'm not sure how often having a backtrace in a commit message will really
help the reader understand why the patch was written.  But perhaps I'm
wrong?

If we do want this advice in our already-too-long submitting-patches
document, we should perhaps give some advice as to what is "relevant
information" and what is not?

Thanks,

jon