CONTRIBUTING.d/patches: Please provide a git-range-diff(1)

[thirdparty/man-pages.git] / CONTRIBUTING.d / patches

diff --git a/CONTRIBUTING.d/patches b/CONTRIBUTING.d/patches
index 71735d3a02b91c508dba79c0d7ac46e5521b7165..afd8c2e3637721721edcc50f096bcd70cb3c8382 100644 (file)
--- a/CONTRIBUTING.d/patches
+++ b/CONTRIBUTING.d/patches
@@ -88,6 +88,35 @@ Description
        -  Make patches against the latest version of the manual page.
           Use git(1) for getting the latest version.
 
+   Prepare the patches for email submission
+       We recommend using git-format-patch(1) to prepare the patches.
+       Please use --range-diff to document the differences between
+       revisions of the patch set, even in the first revision.
+
+       To prepare a branch to be sent as a patch set (v1):
+
+           $ git format-patch -o ./patches master..HEAD \
+                   --range-diff=master -v1 --cover-letter;
+
+       The range diff will be included in the cover letter (or in a
+       single patch, if there is only one):
+
+           $ tail -n7 ./patches/v1-0000-cover-letter.patch;
+           Range-diff against v0:
+           -:  --------- > 1:  7ec952012 foo.3: tfix
+           -:  --------- > 2:  d80376b08 bar.3: ffix
+           -:  --------- > 3:  892a12470 foo.3: wfix
+           --
+           2.43.0
+
+       To send a v2 after some feedback:
+
+           $ git format-patch -o ./patches master..HEAD \
+                   --range-diff=old_master..old_HEAD -v2 --cover-letter;
+
+       The values for 'old_master' and 'old_HEAD' can be consulted in
+       the previous cover letter.  In this example, it would be
+       '--range-diff=7ec952012^..892a12470'.
 
    Send the patches
        We recommend using git-send-email(1) to send the patches to the
@@ -122,5 +151,6 @@ See also
        CONTRIBUTING.d/*
 
        <https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>
+       <https://inbox.sourceware.org/gcc/ZiV5unTogyI7rPJA@debian/>
        <https://git-send-email.io/>
        <https://neomutt.org/feature/cli-crypto>