Skip to content

Commit 3f997cb

Browse files
a3fJonathan Corbet
authored andcommitted
docs: process: submitting-patches: split canonical patch format section
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 <[email protected]> Link: https://lore.kernel.org/r/20241220-submitting-patches-imperative-v1-1-ee874c1859b3@pengutronix.de Signed-off-by: Jonathan Corbet <[email protected]>
1 parent 7cc8cd8 commit 3f997cb

File tree

1 file changed

+34
-22
lines changed

1 file changed

+34
-22
lines changed

Documentation/process/submitting-patches.rst

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -610,6 +610,9 @@ that, if you have your patches stored in a ``git`` repository, proper patch
610610
formatting can be had with ``git format-patch``. The tools cannot create
611611
the necessary text, though, so read the instructions below anyway.
612612

613+
Subject Line
614+
^^^^^^^^^^^^
615+
613616
The canonical patch subject line is::
614617

615618
Subject: [PATCH 001/123] subsystem: summary phrase
@@ -683,6 +686,9 @@ Here are some good example Subjects::
683686
Subject: [PATCH v2] sub/sys: Condensed patch summary
684687
Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
685688

689+
From Line
690+
^^^^^^^^^
691+
686692
The ``from`` line must be the very first line in the message body,
687693
and has the form:
688694

@@ -693,6 +699,9 @@ patch in the permanent changelog. If the ``from`` line is missing,
693699
then the ``From:`` line from the email header will be used to determine
694700
the patch author in the changelog.
695701

702+
Explanation Body
703+
^^^^^^^^^^^^^^^^
704+
696705
The explanation body will be committed to the permanent source
697706
changelog, so should make sense to a competent reader who has long since
698707
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
708717
someone searching for the patch can find it. As in the ``summary
709718
phrase``, it is important to be both succinct as well as descriptive.
710719

720+
.. _backtraces:
721+
722+
Backtraces in commit messages
723+
"""""""""""""""""""""""""""""
724+
725+
Backtraces help document the call chain leading to a problem. However,
726+
not all backtraces are helpful. For example, early boot call chains are
727+
unique and obvious. Copying the full dmesg output verbatim, however,
728+
adds distracting information like timestamps, module lists, register and
729+
stack dumps.
730+
731+
Therefore, the most useful backtraces should distill the relevant
732+
information from the dump, which makes it easier to focus on the real
733+
issue. Here is an example of a well-trimmed backtrace::
734+
735+
unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
736+
at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
737+
Call Trace:
738+
mba_wrmsr
739+
update_domains
740+
rdtgroup_mkdir
741+
742+
Commentary
743+
^^^^^^^^^^
744+
711745
The ``---`` marker line serves the essential purpose of marking for
712746
patch handling tools where the changelog message ends.
713747

@@ -746,28 +780,6 @@ patch::
746780
See more details on the proper patch format in the following
747781
references.
748782

749-
.. _backtraces:
750-
751-
Backtraces in commit messages
752-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
753-
754-
Backtraces help document the call chain leading to a problem. However,
755-
not all backtraces are helpful. For example, early boot call chains are
756-
unique and obvious. Copying the full dmesg output verbatim, however,
757-
adds distracting information like timestamps, module lists, register and
758-
stack dumps.
759-
760-
Therefore, the most useful backtraces should distill the relevant
761-
information from the dump, which makes it easier to focus on the real
762-
issue. Here is an example of a well-trimmed backtrace::
763-
764-
unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
765-
at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
766-
Call Trace:
767-
mba_wrmsr
768-
update_domains
769-
rdtgroup_mkdir
770-
771783
.. _explicit_in_reply_to:
772784

773785
Explicit In-Reply-To headers

0 commit comments

Comments
 (0)