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

[Sean Christopherson]

On Tue, Dec 22, 2020, Borislav Petkov wrote:
> Ok, here's the next one which I think, is also, not really controversial.

Heh, are you trying to jinx yourself?

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

I'd argue that there is still value in the backtrace though, e.g. I find them
very helpful when doing git archaeology.  A backtrace is an easily recognizable
signature (don't have to read a bunch of text to understand there was a splat of
some kind), and the call stack is often helpful even if it is unique, e.g. for
unfamiliar code (including early boot chains) and/or code that is substantially
different from the current upstream.

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

I'd prefer not to encourage people to strip the info after the function name,
though I do agree it's somewhat distracting (especially the offset/size).  The
module, call site in the function, exact file/line if available, etc... provides
context that I find helpful for building a mental model of what went wrong.
E.g. which modules are in play, which short wrapper functions can likely be
glossed over, etc...