[PATCH v2 0/5] SubmittingPatches: update and flesh out trailer sections

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied) kh/submittingpatches-trailers

Topic summary: Flesh out and update the trailer sections.

All of these points have come up on the mailing list. At least for me.
And `Based-on-patch-by` is a nice-to-have documented kind of thing.

[elide “since January” from v1...]

Link to v1: https://lore.kernel.org/git/CV_SubPatches_trailers.8f3@msgid.xyz/

§ Changes in v2

See the patch Notes for details.

• Improve commit messages
• Drop patch “discuss non-ident trailers”
  • https://lore.kernel.org/git/CV_SubPatches_trailers.8f3@msgid.xyz/T/#m53305dbb8c1f19b06be781ee720fc3be875a326d
• Rewrite “note that trailer order matters” to emphasize chronological
  order and to also mention it in the DCO section
    • See https://lore.kernel.org/git/xmqq8q8mt4eo.fsf@gitster.g/

[1/5] SubmittingPatches: encourage trailer use for substantial help
[2/5] SubmittingPatches: discourage common Linux trailers
[3/5] SubmittingPatches: document Based-on-patch-by trailer
[4/5] SubmittingPatches: be consistent with trailer markup
[5/5] SubmittingPatches: note that trailer order matters

 Documentation/SubmittingPatches | 46 ++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 10 deletions(-)

Interdiff against v1:
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 89542263444..dceeb5a1817 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -427,6 +427,10 @@ D-C-O.  Indeed you are encouraged to do so.  Do not forget to
 place an in-body "From: " line at the beginning to properly attribute
 the change to its true author (see (2) above).
 
+Place this `Signed-off-by:` trailer at the end, after trailers added by
+others and after other trailers added by you; see
+<<commit-trailers,Commit trailers>> below ("chronological order").
+
 This procedure originally came from the Linux kernel project, so our
 rule is quite similar to theirs, but what exactly it means to sign-off
 your patch differs from project to project, so it may be different
@@ -467,8 +471,8 @@ These are the common trailers in use:
    of a patch before submitting it.
 . `Based-on-patch-by:` is used when someone else authored parts of the
   patch that you are submitting. This might be relevant if someone sent
-  a patch to the mailing list without a commit message or a
-  `Signed-off-by:` and you have picked it up.
+  a patch to the mailing list with their sign-off. (Be mindful and ask
+  them to sign off on it if they did not.)
 . `Helped-by:` is used to credit someone who suggested ideas for
   changes without providing the precise changes in patch form.
 . `Mentored-by:` is used to credit someone with helping develop a
@@ -478,10 +482,7 @@ These are the common trailers in use:
 
 While you can also create your own trailer if the situation warrants it, we
 encourage you to instead use one of the common trailers in this project
-highlighted above. A trailer that credits someone might be more likely
-to be accepted since these are the most common ones. But another kind of
-trailer might be relevant, for example to link to an issue tracker
-belonging to a downstream project that is affected by a bug in Git.
+highlighted above.
 
 Other projects might regularly refer to other kinds of data, like
 `Fixes:` and `Link:` in the Linux Kernel project, but these ones in
@@ -490,10 +491,11 @@ particular are not used in this project.
 Only capitalize the very first letter of the trailer, i.e. favor
 `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.
 
-Note that these trailers should come before your `Signed-off-by:`
-trailer. You are signing off to the patch as well as the message. This
-also makes it clear who added trailers when multiple people have signed
-off on a patch.
+As mentioned under <<dco,DCO>> above, trailers are added in
+chronological order; one person might sign-off on a patch and send it to
+someone else, who then in turn adds her own sign-off. Further, any
+trailers that you add beyond your sign-off should come before that
+sign-off. That makes it clear what trailers which person added.
 
 [[ai]]
 === Use of Artificial Intelligence (AI)
Range-diff against v1:
1:  366c0f43b71 ! 1:  835eb736f39 SubmittingPatches: encourage trailer use for substantial help
    @@ Commit message
         contribution”.[2]
     
         Adding trailers is already encouraged, but in the section `send-patches`.
    -    Let’s replace “If you like” with outright encouragment in this section
    +    Let’s replace “If you like” with outright encouragement in this section
         so that all trailer discussion (except s-o-b; see `sign-off` section) is
         contained in this section; a link to from `send-patches` makes this
         information equally visible.
    @@ Commit message
         Now we need to make a heading for `commit-trailers` in order for the
         HTML output to make sense.
     
    -    At the same, it is important to temper this recommendation to a sign-
    -    ificant enough contribution; in my experience beginners can be eager
    +    At the same time, it is important to temper this recommendation to a
    +    significant enough contribution; in my experience beginners can be eager
         to add a trailer for everyone who replies with an action point that is
         followed up on.
     
2:  c78fb49c245 < -:  ----------- SubmittingPatches: discuss non-ident trailers
3:  cff069ced4e ! 2:  5a652b8e14d SubmittingPatches: discourage common Linux trailers
    @@ Commit message
         git.git `master` from time to time.
     
         This project does regularly mention what commits a patch/commit fixes,
    -    but that is done inline in the commit message proper (c.f. the trailer
    +    but that is done inline in the commit message proper (cf. the trailer
         block of the message).
     
         For `Link`: These are used both to link back to the patch submission as
    @@ Commit message
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/SubmittingPatches ##
    -@@ Documentation/SubmittingPatches: to be accepted since these are the most common ones. But another kind of
    - trailer might be relevant, for example to link to an issue tracker
    - belonging to a downstream project that is affected by a bug in Git.
    +@@ Documentation/SubmittingPatches: While you can also create your own trailer if the situation warrants it, we
    + encourage you to instead use one of the common trailers in this project
    + highlighted above.
      
     +Other projects might regularly refer to other kinds of data, like
     +`Fixes:` and `Link:` in the Linux Kernel project, but these ones in
4:  278eb2c5d21 ! 3:  5e53999b2e9 SubmittingPatches: document Based-on-patch-by trailer
    @@ Documentation/SubmittingPatches: These are the common trailers in use:
         of a patch before submitting it.
     +. `Based-on-patch-by:` is used when someone else authored parts of the
     +  patch that you are submitting. This might be relevant if someone sent
    -+  a patch to the mailing list without a commit message or a
    -+  `Signed-off-by:` and you have picked it up.
    ++  a patch to the mailing list with their sign-off. (Be mindful and ask
    ++  them to sign off on it if they did not.)
      . `Helped-by:` is used to credit someone who suggested ideas for
        changes without providing the precise changes in patch form.
      . `Mentored-by:` is used to credit someone with helping develop a
5:  347c72e4e08 = 4:  dd47fabe917 SubmittingPatches: be consistent with trailer markup
6:  1c7e9ad8e69 ! 5:  20f04e18cee SubmittingPatches: note that trailer order matters
    @@ Metadata
      ## Commit message ##
         SubmittingPatches: note that trailer order matters
     
    -    It matters where you put the s-o-b; it should be last. You are signing
    -    off on the patch as well as the whole message up to that point.
    +    It matters where you put new trailers: they should be added in
    +    chronological order, and each person who passes on a patch should add
    +    their s-o-b last. You are signing off on the patch as well as the whole
    +    message up to that point.
     
         This also makes it clear who added what:
     
    @@ Commit message
             Acked-by: The (Late) Reviewer <late@example.org>
             Signed-off-by: The Maintainer <m@example.org>
     
    -    The the first ack was added by the contributor and the second one was
    -    added by the maintainer.
    +    The first ack was added by the contributor and the second one was added
    +    by the maintainer.
     
    +    Helped-by: Junio C Hamano <gitster@pobox.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/SubmittingPatches ##
    +@@ Documentation/SubmittingPatches: D-C-O.  Indeed you are encouraged to do so.  Do not forget to
    + place an in-body "From: " line at the beginning to properly attribute
    + the change to its true author (see (2) above).
    + 
    ++Place this `Signed-off-by:` trailer at the end, after trailers added by
    ++others and after other trailers added by you; see
    ++<<commit-trailers,Commit trailers>> below ("chronological order").
    ++
    + This procedure originally came from the Linux kernel project, so our
    + rule is quite similar to theirs, but what exactly it means to sign-off
    + your patch differs from project to project, so it may be different
     @@ Documentation/SubmittingPatches: particular are not used in this project.
      Only capitalize the very first letter of the trailer, i.e. favor
      `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.
      
    -+Note that these trailers should come before your `Signed-off-by:`
    -+trailer. You are signing off to the patch as well as the message. This
    -+also makes it clear who added trailers when multiple people have signed
    -+off on a patch.
    ++As mentioned under <<dco,DCO>> above, trailers are added in
    ++chronological order; one person might sign-off on a patch and send it to
    ++someone else, who then in turn adds her own sign-off. Further, any
    ++trailers that you add beyond your sign-off should come before that
    ++sign-off. That makes it clear what trailers which person added.
     +
      [[ai]]
      === Use of Artificial Intelligence (AI)

base-commit: 1ff279f3404a482a83fb04c7457e41ab26884aea
-- 
2.54.0.22.g9e26862b904