tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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 <a.fatoum@pengutronix.de>
Link: https://lore.kernel.org/r/20241220-submitting-patches-imperative-v1-1-ee874c1859b3@pengutronix.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

authored by

Ahmad Fatoum and committed by
Jonathan Corbet 3f997cbf 7cc8cd8c

+34 -22
+34 -22
Documentation/process/submitting-patches.rst
··· 610 610 formatting can be had with ``git format-patch``. The tools cannot create 611 611 the necessary text, though, so read the instructions below anyway. 612 612 613 + Subject Line 614 + ^^^^^^^^^^^^ 615 + 613 616 The canonical patch subject line is:: 614 617 615 618 Subject: [PATCH 001/123] subsystem: summary phrase ··· 686 683 Subject: [PATCH v2] sub/sys: Condensed patch summary 687 684 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary 688 685 686 + From Line 687 + ^^^^^^^^^ 688 + 689 689 The ``from`` line must be the very first line in the message body, 690 690 and has the form: 691 691 ··· 698 692 patch in the permanent changelog. If the ``from`` line is missing, 699 693 then the ``From:`` line from the email header will be used to determine 700 694 the patch author in the changelog. 695 + 696 + Explanation Body 697 + ^^^^^^^^^^^^^^^^ 701 698 702 699 The explanation body will be committed to the permanent source 703 700 changelog, so should make sense to a competent reader who has long since ··· 716 707 _all_ of the compile failures; just enough that it is likely that 717 708 someone searching for the patch can find it. As in the ``summary 718 709 phrase``, it is important to be both succinct as well as descriptive. 710 + 711 + .. _backtraces: 712 + 713 + Backtraces in commit messages 714 + """"""""""""""""""""""""""""" 715 + 716 + Backtraces help document the call chain leading to a problem. However, 717 + not all backtraces are helpful. For example, early boot call chains are 718 + unique and obvious. Copying the full dmesg output verbatim, however, 719 + adds distracting information like timestamps, module lists, register and 720 + stack dumps. 721 + 722 + Therefore, the most useful backtraces should distill the relevant 723 + information from the dump, which makes it easier to focus on the real 724 + issue. Here is an example of a well-trimmed backtrace:: 725 + 726 + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) 727 + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) 728 + Call Trace: 729 + mba_wrmsr 730 + update_domains 731 + rdtgroup_mkdir 732 + 733 + Commentary 734 + ^^^^^^^^^^ 719 735 720 736 The ``---`` marker line serves the essential purpose of marking for 721 737 patch handling tools where the changelog message ends. ··· 779 745 780 746 See more details on the proper patch format in the following 781 747 references. 782 - 783 - .. _backtraces: 784 - 785 - Backtraces in commit messages 786 - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 787 - 788 - Backtraces help document the call chain leading to a problem. However, 789 - not all backtraces are helpful. For example, early boot call chains are 790 - unique and obvious. Copying the full dmesg output verbatim, however, 791 - adds distracting information like timestamps, module lists, register and 792 - stack dumps. 793 - 794 - Therefore, the most useful backtraces should distill the relevant 795 - information from the dump, which makes it easier to focus on the real 796 - issue. Here is an example of a well-trimmed backtrace:: 797 - 798 - unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) 799 - at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) 800 - Call Trace: 801 - mba_wrmsr 802 - update_domains 803 - rdtgroup_mkdir 804 748 805 749 .. _explicit_in_reply_to: 806 750