@@ -610,6 +610,9 @@ that, if you have your patches stored in a ``git`` repository, proper patch
610610formatting can be had with ``git format-patch ``. The tools cannot create
611611the necessary text, though, so read the instructions below anyway.
612612
613+ Subject Line
614+ ^^^^^^^^^^^^
615+
613616The 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+
686692The ``from `` line must be the very first line in the message body,
687693and has the form:
688694
@@ -693,6 +699,9 @@ patch in the permanent changelog. If the ``from`` line is missing,
693699then the ``From: `` line from the email header will be used to determine
694700the patch author in the changelog.
695701
702+ Explanation Body
703+ ^^^^^^^^^^^^^^^^
704+
696705The explanation body will be committed to the permanent source
697706changelog, so should make sense to a competent reader who has long since
698707forgotten 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
708717someone searching for the patch can find it. As in the ``summary
709718phrase ``, 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+
711745The ``--- `` marker line serves the essential purpose of marking for
712746patch handling tools where the changelog message ends.
713747
@@ -746,28 +780,6 @@ patch::
746780See more details on the proper patch format in the following
747781references.
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
773785Explicit In-Reply-To headers
0 commit comments