[PATCH v2 0/5] SubmittingPatches: update and flesh out trailer sections
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:
Show changes to Documentation/SubmittingPatches +12 −10
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