Clarify and expand description of --signoff
cover Clarify and expand description of --signoff
As you know, it's rare that Conservancy offers specific patches upstream to our member projects, but I've attached a patch that updates the documentation regarding Signed-Off-By.
While the Git and Linux projects use this specifically to refer to a DCO as published on the URL provided, other projects have various meanings of Signed-Off-By, and we noticed in a recent check of Conservancy member projects that details on it vary. Ultimately, I don't think Git wants anyway to opine about the meaning of Signed-off-by for every project that uses Git, so this documentation change hedges while still explaning and recommending the DCO used by Linux and Git.
Peff gave me some feedback on this change and we did a bit of redrafting in a private email thread, but I think this is now ready for public review and discussion.
I apologize in advance if I've made a mistake in format or form in submitting this patch; it's my first upstream contribution to Git! I did try my best to follow Documentation/MyFirstContribution.txt carefully! :)
Bradley M. Kuhn (1):
Documentation: Clarify and expand description of --signoff
Documentation/git-commit.txt | 13 ++++++++----- Documentation/merge-options.txt | 13 ++++++++----- 2 files changed, 16 insertions(+), 10 deletions(-)
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
PATCH 1/1 Documentation: Clarify and expand description of --signoff
Building on past documentation improvements in Commit b2c150d3aa (Expand documentation describing --signoff, 2016-01-05), further clarify that any project using Git may and often does set its own policy.
However, leave intact reference to the Linux DCO, which Git also uses. It is reasonable for Git to advocate for its own Signed-off-by methodology in its documentation, as long as the documentation remains respectful that YMMV and other projects may well have very different contributor representations tied to Signed-off-by.
--- Documentation/git-commit.txt | 13 ++++++++----- Documentation/merge-options.txt | 13 ++++++++----- 2 files changed, 16 insertions(+), 10 deletions(-)
Documentation/git-commit.txt +8 -5
@@ -166,11 +166,14 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. -s:: --signoff:: Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). + log message. The meaning of a signoff depends on the project to which + you're committing. For example, it may certify that the committer has + the rights to submit the work under the project's license or agrees to + some contributor representation, such as a Developer Certificate of + Origin. (See http://developercertificate.org for the one used by the + Linux kernel and Git projects.) Consult the documentation or + leadership of the project to which you're contributing to understand + how the signoffs are used in that project. -n:: --no-verify::
Documentation/merge-options.txt +8 -5
@@ -80,11 +80,14 @@ actual commits being merged. --signoff:: --no-signoff:: Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). + log message. The meaning of a signoff depends on the project to which + you're committing. For example, it may certify that the committer has + the rights to submit the work under the project's license or agrees to + some contributor representation, such as a Developer Certificate of + Origin. (See http://developercertificate.org for the one used by the + Linux kernel and Git projects.) Consult the documentation or + leadership of the project to which you're contributing to understand + how the signoffs are used in that project. + With --no-signoff do not add a Signed-off-by line.
Signature · 1 line
2.26.1
Re: [PATCH 1/1] Documentation: Clarify and expand description of --signoff
Quoted 10 lines · Bradley M. Kuhn
Building on past documentation improvements in Commit
b2c150d3aa(Expand documentation describing --signoff, 2016-01-05), further clarify that any project using Git may and often does set its own policy.However, leave intact reference to the Linux DCO, which Git also uses. It is reasonable for Git to advocate for its own Signed-off-by methodology in its documentation, as long as the documentation remains respectful that YMMV and other projects may well have very different contributor representations tied to Signed-off-by.
I think this is worth doing, and doesn't really change the intent of what we were trying to do with b2c150d3aa. It just says it a bit more clearly, IMHO.
Except for one minor nit below, the patch looks good to me. Unsurprisingly, since as you mentioned we discussed it off-list already. :)
To be clear, it's...
as far as any words I contributed.
As far as your patch formatting, submission, etc, it looks OK. I probably would've kept "clarify" in the title as lowercase. I'd also usually not do a separate cover letter for a single-patch series (and instead put anything not meant for the commit message after the "---" line). But that's mostly a matter of taste (a lot of people do separate cover letters).
Documentation/merge-options.txt
Quoted 7 lines
Documentation/merge-options.txt +2
-0+ leadership of the project to which you're contributing to understand + how the signoffs are used in that project.
Extra leading space on this final line.
-Peff
PS Since this is your first patch submission, welcome to the Git
project. ;)
Re: [PATCH 1/1] Documentation: Clarify and expand description of --signoff
In reply to Bradley M. KuhnDocumentation/git-commit.txt The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. · line 168
Quoted 8 lines · Bradley M. Kuhn
Documentation/git-commit.txt +0
-0@@ -166,11 +166,14 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. -s:: --signoff:: Add Signed-off-by line by the committer at the end of the commit
While we're editing this, how about changing the above to read:
Add a Signed-off-by line...
to fix a grammer nit. We do use a similar formulation later the git merge-options man page:
Documentation/merge-options.txt actual commits being merged. · line 82
Quoted 11 lines
Documentation/git-commit.txt +0
-0With --no-signoff do not add a Signed-off-by line.Documentation/merge-options.txt +0
-0@@ -80,11 +80,14 @@ actual commits being merged. --signoff:: --no-signoff:: Add Signed-off-by line by the committer at the end of the commit
... and again here.
Thanks!
- Ted
Hi Bradley,
Quoted 6 lines · Bradley M. Kuhn
Documentation/git-commit.txt| 13 ++++++++-----Documentation/merge-options.txt| 13 ++++++++-----2 files changed, 16 insertions(+), 10 deletions(-)
Since the changes are exactly the same in the two files, maybe a preparatory patch that creates 'signoff.txt' and includes it in 'git-commit.txt' and 'merge-options.txt' would be a good idea ?
Cheers,
Philippe.
Quoted 7 lines
Quoted 3 lines
Documentation/git-commit.txt| 13 ++++++++-----Documentation/merge-options.txt| 13 ++++++++-----2 files changed, 16 insertions(+), 10 deletions(-)Since the changes are exactly the same in the two files, maybe a preparatory patch that creates 'signoff.txt' and includes it in 'git-commit.txt' and 'merge-options.txt' would be a good idea ?
I actually think we are OK with two duplicated and leave that for later clean-up. The more important would be to polish the text into a good enough state quickly.
Another thing we should not forget is to update our SubmittingPatches document. Since we are placing extra stress on that there is NO inherent meaning in "sign off" and it is largely up to each project, we should set a good example explaining what it means to THIS project to sign your patches off, and SubmittingPatches is the document to do so. Without such an update, I think the update to these two files we see in this patch is incomplete.
Thanks.
Quoted 12 lines · Junio C Hamano
Quoted 7 lines
Quoted 3 lines
Documentation/git-commit.txt| 13 ++++++++-----Documentation/merge-options.txt| 13 ++++++++-----2 files changed, 16 insertions(+), 10 deletions(-)Since the changes are exactly the same in the two files, maybe a preparatory patch that creates 'signoff.txt' and includes it in 'git-commit.txt' and 'merge-options.txt' would be a good idea ?
I actually think we are OK with two duplicated and leave that for later clean-up. The more important would be to polish the text into a good enough state quickly.
Quoted 7 lines
Another thing we should not forget is to update our SubmittingPatches document. Since we are placing extra stress on that there is NO inherent meaning in "sign off" and it is largely up to each project, we should set a good example explaining what it means to THIS project to sign your patches off, and SubmittingPatches is the document to do so. Without such an update, I think the update to these two files we see in this patch is incomplete.
I agree we should be leading by example here.
We do already say pretty clearly what signed-off-by means in the project:
$ grep -A14 '\[\[sign-off]]' Documentation/SubmittingPatches [[sign-off]] === Certify your work by adding your "Signed-off-by: " line
To improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches that are being emailed around. Although core Git is a lot smaller project it is a good discipline to follow it.
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below D-C-O:
[[dco]]
.Developer's Certificate of Origin 1.1
What should we change there? We could perhaps bring up signoffs earlier or more prominently. Or tie it in to the git-commit docs by saying
explicitly: these are _our_ project rules for signoffs.
-Peff
Quoted 17 lines · Jeff King
We do already say pretty clearly what signed-off-by means in the project:
$ grep -A14 '\[\[sign-off]]' Documentation/SubmittingPatches [[sign-off]] === Certify your work by adding your "Signed-off-by: " lineTo improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches that are being emailed around. Although core Git is a lot smaller project it is a good discipline to follow it.
The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below D-C-O:
Quoted 6 lines
[[dco]]
.Developer's Certificate of Origin 1.1What should we change there? We could perhaps bring up signoffs earlier or more prominently. Or tie it in to the git-commit docs by saying
explicitly: these are _our_ project rules for signoffs.
That is almost good enough, but you can easily see that it was written back when the world only had choice between "Linux-style signed-off-by that means Linux-style DCO requirement" and "not signing off", and we chose to be in the former camp.
I think the most important clarification Bradley's making is that we no longer live in such a world. "signed-off-by" means different things for different projects, and what we use is this one. That choice may have been adopted from the Linux project and may have been identical to what they used back when we adopted it, but that is of secondary importance (most importantly, if they changed what it means, that won't directly affect this project).
Perhaps I'd rewrite these two paragraphs like so:
To improve tracking of who did what, we use the "sign off" procedure. By adding the "Signed-off-by:" line in the trailer of your commit, you certify to this project the below D-C-O that you have the right to pass your patch on under the same license as ours. Without such a sign-off, we cannot accept your patch:
[[dco]]
.Developer's Certificate of Origin 1.1
...
and after the DCO text, add this paragraph as a historical reference.
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 from that of the project you are accustomed to.
either before or after the "Random J Developer" example. I think we should remove the "you can do this automatically by giving -s" or at least the word "automatically" from that sentence, while we are at it.
Thanks.
Quoted 5 lines
Quoted 3 lines · Jeff King
What should we change there? We could perhaps bring up signoffs earlier or more prominently. Or tie it in to the git-commit docs by saying
explicitly: these are _our_ project rules for signoffs.
Let's tie this loose end. How about squashing in something like this?
-- >8 --
Subject: SubmittingPatches: clarify DCO is our --signoff rule
The description on sign-off and DCO was written back in the days where there was only a choice between "use sign-off and it means the contributor agrees to the Linux-kernel style DCO" and "not using sign-off at all will make your patch unusable". These days, we are trying to clarify that the exact meaning of a sign-off varies project to project.
Let's be more explicit when presenting what _our_ rules are. It is of secondary importance that it originally came from the kernel project, so move the description as a historical note at the end, while cautioning that what a sign-off means to us may be different from what it means to other projects contributors may have been used to.
--- Documentation/SubmittingPatches | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-)
Documentation/SubmittingPatches +14 -11
@@ -300,15 +300,12 @@ patch. [[sign-off]] === Certify your work by adding your "Signed-off-by: " line -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although core Git is a lot -smaller project it is a good discipline to follow it. +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. -The sign-off is a simple line at the end of the explanation for -the patch, which certifies that you wrote it or otherwise have -the right to pass it on as an open-source patch. The rules are -pretty simple: if you can certify the below D-C-O: +If you can certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1
@@ -338,14 +335,15 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -then you just add a line saying +you add a "Signed-off-by" trailer to your commit, that looks like +this: .... Signed-off-by: Random J Developer <[email protected]> .... -This line can be automatically added by Git if you run the git-commit -command with the -s option. +This line can be added by Git if you run the git-commit command with +the -s option. Notice that you can place your own Signed-off-by: line when forwarding somebody else's patch with the above rules for
@@ -353,6 +351,11 @@ 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). +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 +from that of the project you are accustomed to. + [[real-name]] Also notice that a real name is used in the Signed-off-by: line. Please don't hide your real name.
Quoted 8 lines · Junio C Hamano
Quoted 5 lines
Quoted 3 lines · Jeff King
What should we change there? We could perhaps bring up signoffs earlier or more prominently. Or tie it in to the git-commit docs by saying
explicitly: these are _our_ project rules for signoffs.Let's tie this loose end. How about squashing in something like this?
Thanks for writing this up. I agree it makes the text much better (not only in emphasizing the point we've been discussing, but also in general clarity).
You said "squashing", but I'd suggest keeping it as its own patch on top of Bradley's.
-Peff
Quoted 2 lines · Jeff King
You said "squashing", but I'd suggest keeping it as its own patch on top of Bradley's.
While I admit a certain vain desire to have my name appear in Git's own commit history (given that it's unlikely I'll ever be able to spare the time to make another contribution), if it's cleaner to squash my change, I can assent to that and you can consider both patches discussed in this thread together:
--
Bradley M. Kuhn - he/him
Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Quoted 11 lines · Jeff King
Quoted 8 lines · Junio C Hamano
Quoted 5 lines
Quoted 3 lines · Jeff King
What should we change there? We could perhaps bring up signoffs earlier or more prominently. Or tie it in to the git-commit docs by saying
explicitly: these are _our_ project rules for signoffs.Let's tie this loose end. How about squashing in something like this?
Quoted 6 lines
Thanks for writing this up. I agree it makes the text much better (not only in emphasizing the point we've been discussing, but also in general clarity).
You said "squashing", but I'd suggest keeping it as its own patch on top of Bradley's.
OK, let's do so.
I recall I read that Bradley's patch needs a bit of word/grammo polishing?
Thanks.
Quoted 17 lines · Junio C Hamano
Quoted 15 lines · Jeff King
Quoted 8 lines · Junio C Hamano
Quoted 5 lines
Quoted 3 lines · Jeff King
What should we change there? We could perhaps bring up signoffs earlier or more prominently. Or tie it in to the git-commit docs by saying
explicitly: these are _our_ project rules for signoffs.Let's tie this loose end. How about squashing in something like this?
Thanks for writing this up. I agree it makes the text much better (not only in emphasizing the point we've been discussing, but also in general clarity).
Quoted 7 lines
Quoted 2 lines
You said "squashing", but I'd suggest keeping it as its own patch on top of Bradley's.
OK, let's do so.
I recall I read that Bradley's patch needs a bit of word/grammo polishing?
Well, I pointed out a missing article ("a") in the line *above* Bradley's change in two man pages. It's a minor nit, and it's unrelated to his proposed change. I have no opinion about whether it's better to do it separately from his change or as a separate commit.
- Ted
Quoted 5 lines · Theodore Y. Ts'o
Quoted 5 lines
Quoted 2 lines
You said "squashing", but I'd suggest keeping it as its own patch on top of Bradley's.
OK, let's do so.
Quoted 8 lines
Quoted 2 lines
I recall I read that Bradley's patch needs a bit of word/grammo polishing?
Well, I pointed out a missing article ("a") in the line *above* Bradley's change in two man pages. It's a minor nit, and it's unrelated to his proposed change. I have no opinion about whether it's better to do it separately from his change or as a separate commit.
Thanks for reminding me. In any case, an updated version that ended up being a 3-patch series is now on the table. I think they are in good shape to be merged down.
Thanks.
v2 cover clarify and expand description of --signoff & related fixes
Jeff wrote last week:
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
You said "squashing", but I'd suggest keeping it as its own patch on top of Bradley's.
Junio replied last week:
Quoted 1 line
Quoted 1 line
OK, let's do so.
Theodore Ts'o wrote today at 08:53 (PDT):
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
I pointed out a missing article ("a") in the line *above* ... It's a minor nit, and it's unrelated to his proposed change.
Junio C Hamano replied today at 11:26 (PDT):
Quoted 3 lines
In any case, an updated version that ended up
being a 3-patch series is now on the table. I think they are in good shape to be merged down.
Herein is (I believe) the three-patch series that Junio references. The middle patch didn't exist yet because Ted just pointed out the typo and didn't have a patch, but I've done the typo fix and credited Ted on that in the commit.
However, the middle commit ([PATCH v2 2/3]) needs some review. I ended up down the rabbit hole of "what is the consistent way in which the Git documentation refers to Signed-off-by?" and I found many inconsistencies. I've normalized around a style convention described in that patch's commit message.
Meanwhile, I also note that SubmittingPatches now calls these "trailers" rather than "lines", so maybe we should be using the word "trailer" rather than "line" consistently in the other documentation? If folks think that should be done, I can redo this patchset to go that route.
Alternatively, if anyone has any strong opinions on the normalization to:
(a|the) Signed-off-by: line
in documentation formatting when referring to Signed-off-by, please say so.
Thanks everyone for your comments and help on this!
I also added these, as Jeff King wrote about at 17:46 (PDT) on Thursday:
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
To be clear, it's...
Signed-off-by Jeff King <[email protected]>as far as any words I contributed.
Added.
Quoted 1 line
Quoted 1 line
Quoted 1 line
I probably would've kept "clarify" in the title as lowercase.
Fixed.
Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
Quoted 7 lines
Documentation/merge-options.txt
Quoted 7 lines
Documentation/merge-options.txt +2
-0+ leadership of the project to which you're contributing to understand + how the signoffs are used in that project.Extra leading space on this final line.
Also fixed.
Bradley M. Kuhn (2):
Documentation: clarify and expand description of --signoff
Documentation: stylistically normalize references to Signed-off-by:
Junio C Hamano (1):
SubmittingPatches: clarify DCO is our --signoff rule
Documentation/MyFirstContribution.txt | 2 +- Documentation/SubmittingPatches | 35 +++++++++++++++------------ Documentation/git-cherry-pick.txt | 2 +- Documentation/git-commit.txt | 15 +++++++----- Documentation/git-format-patch.txt | 2 +- Documentation/git-rebase.txt | 2 +- Documentation/git-revert.txt | 2 +- Documentation/git-send-email.txt | 4 +-- Documentation/githooks.txt | 2 +- Documentation/merge-options.txt | 17 +++++++------ builtin/am.c | 2 +- builtin/commit.c | 2 +- builtin/log.c | 2 +- builtin/merge.c | 2 +- builtin/pull.c | 2 +- builtin/revert.c | 2 +- 16 files changed, 52 insertions(+), 43 deletions(-)
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
PATCH v2 1/3 Documentation: clarify and expand description of --signoff
Building on past documentation improvements in Commit b2c150d3aa (Expand documentation describing --signoff, 2016-01-05), further clarify that any project using Git may and often does set its own policy.
However, leave intact reference to the Linux DCO, which Git also uses. It is reasonable for Git to advocate for its own Signed-off-by methodology in its documentation, as long as the documentation remains respectful that YMMV and other projects may well have very different contributor representations tied to Signed-off-by.
--- Documentation/git-commit.txt | 13 ++++++++----- Documentation/merge-options.txt | 13 ++++++++----- 2 files changed, 16 insertions(+), 10 deletions(-)
Documentation/git-commit.txt +8 -5
@@ -166,11 +166,14 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. -s:: --signoff:: Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). + log message. The meaning of a signoff depends on the project to which + you're committing. For example, it may certify that the committer has + the rights to submit the work under the project's license or agrees to + some contributor representation, such as a Developer Certificate of + Origin. (See http://developercertificate.org for the one used by the + Linux kernel and Git projects.) Consult the documentation or + leadership of the project to which you're contributing to understand + how the signoffs are used in that project. -n:: --no-verify::
Documentation/merge-options.txt +8 -5
@@ -80,11 +80,14 @@ actual commits being merged. --signoff:: --no-signoff:: Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). + log message. The meaning of a signoff depends on the project to which + you're committing. For example, it may certify that the committer has + the rights to submit the work under the project's license or agrees to + some contributor representation, such as a Developer Certificate of + Origin. (See http://developercertificate.org for the one used by the + Linux kernel and Git projects.) Consult the documentation or + leadership of the project to which you're contributing to understand + how the signoffs are used in that project. + With --no-signoff do not add a Signed-off-by line.
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
PATCH v2 2/3 Documentation: stylistically normalize references to Signed-off-by:
In reply to Bradley M. KuhnTed reported during patch review of the previous commit that an old typo was present in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article.
Upon examination, it seems that the documentation (including items in Documentation/, but also option help strings) have been quite inconsistent on usage when referring to Signed-off-by:.
It seems the original usage, seen in Commit3f971fc425b (Documentation updates, 2005-08-14) initially used "Add Signed-off-by line", and Commit 6f855371a53 (Add --signoff, --check, and long option-names. 2005-12-09) switched to using "Add Signed-off-by: line", but didn't normalize the former commit to match. Later commits seem to have cut and pasted from one or the other, which is likely how the usage became so inconsistent.
Very few places used a definite or indefinite article with the phrase "Signed-off-by: line", but that was the initial typo that led me down this investigation, so I have normalized using either an indefinite or definite article consistently. Since usage of Signed-off-by: (with the colon) was about six months more current than without the colon, I chose Signed-off-by: (with backticks) for the documentation files and Signed-off-by: (without backticks) for option help strings
I left alone a few places in documentation that used the phrase Signed-off-by (without colon or backticks) to refer to the process (rather than the specific line), and I also left alone one place where many mail headers were mentioned in a specific way so the style for Signed-off-by and those mail headers remained consistent.
Message-ID: <[email protected]>
--- Documentation/MyFirstContribution.txt | 2 +- Documentation/SubmittingPatches | 10 +++++----- Documentation/git-cherry-pick.txt | 2 +- Documentation/git-commit.txt | 2 +- Documentation/git-format-patch.txt | 2 +- Documentation/git-rebase.txt | 2 +- Documentation/git-revert.txt | 2 +- Documentation/git-send-email.txt | 4 ++-- Documentation/githooks.txt | 2 +- Documentation/merge-options.txt | 4 ++-- builtin/am.c | 2 +- builtin/commit.c | 2 +- builtin/log.c | 2 +- builtin/merge.c | 2 +- builtin/pull.c | 2 +- builtin/revert.c | 2 +- 16 files changed, 22 insertions(+), 22 deletions(-)
Documentation/MyFirstContribution.txt +1 -1
@@ -249,7 +249,7 @@ component you're working on, followed by a blank line (always required) and then the body of your commit message, which should provide the bulk of the context. Remember to be explicit and provide the "Why" of your change, especially if it couldn't easily be understood from your diff. When editing your commit message, -don't remove the Signed-off-by line which was added by `-s` above. +don't remove the `Signed-off-by:` line which was added by `-s` above. ---- psuh: add a built-in by popular demand
Documentation/SubmittingPatches +5 -5
@@ -209,7 +209,7 @@ send them as replies to either an additional "cover letter" message (see below), the first patch, or the respective preceding patch. If your log message (including your name on the -Signed-off-by line) is not writable in ASCII, make sure that +`Signed-off-by:` line) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap
@@ -229,7 +229,7 @@ previously sent. The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the -Signed-off-by: lines, and a line that consists of three dashes, +`Signed-off-by:` lines, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit
@@ -298,7 +298,7 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and patch. [[sign-off]] -=== Certify your work by adding your "Signed-off-by: " line +=== Certify your work by adding your `Signed-off-by:` line To improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches
@@ -347,14 +347,14 @@ then you just add a line saying This line can be automatically added by Git if you run the git-commit command with the -s option. -Notice that you can place your own Signed-off-by: line when +Notice that you can place your own `Signed-off-by:` line when forwarding somebody else's patch with the above rules for 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). [[real-name]] -Also notice that a real name is used in the Signed-off-by: line. Please +Also notice that a real name is used in the `Signed-off-by:` line. Please don't hide your real name. [[commit-trailers]]
Documentation/git-cherry-pick.txt +1 -1
@@ -104,7 +104,7 @@ effect to your index in a row. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add a `Signed-off-by:` line at the end of the commit message. See the signoff option in linkgit:git-commit[1] for more information. -S[<keyid>]::
Documentation/git-commit.txt +1 -1
@@ -165,7 +165,7 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. -s:: --signoff:: - Add Signed-off-by line by the committer at the end of the commit + Add a `Signed-off-by:` line by the committer at the end of the commit log message. The meaning of a signoff depends on the project to which you're committing. For example, it may certify that the committer has the rights to submit the work under the project's license or agrees to
Documentation/git-format-patch.txt +1 -1
@@ -119,7 +119,7 @@ include::diff-options.txt[] -s:: --signoff:: - Add `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by:` line to the commit message, using the committer identity of yourself. See the signoff option in linkgit:git-commit[1] for more information.
Documentation/git-rebase.txt +1 -1
@@ -496,7 +496,7 @@ See also INCOMPATIBLE OPTIONS below. See also INCOMPATIBLE OPTIONS below. --signoff:: - Add a Signed-off-by: trailer to all the rebased commits. Note + Add a `Signed-off-by:` trailer to all the rebased commits. Note that if `--interactive` is given then only commits marked to be picked, edited or reworded will have the trailer added. +
Documentation/git-revert.txt +1 -1
@@ -99,7 +99,7 @@ effect to your index in a row. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add a `Signed-off-by:` line at the end of the commit message. See the signoff option in linkgit:git-commit[1] for more information. --strategy=<strategy>::
Documentation/git-send-email.txt +2 -2
@@ -313,7 +313,7 @@ Automating the value of `sendemail.identity`. --[no-]signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the + If this is set, add emails found in the `Signed-off-by:` or Cc: lines to the cc list. Default is the value of `sendemail.signedoffbycc` configuration value; if that is unspecified, default to --signed-off-by-cc.
@@ -340,7 +340,7 @@ Automating except for self (use 'self' for that). - 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). -- 'sob' will avoid including anyone mentioned in Signed-off-by lines except +- 'sob' will avoid including anyone mentioned in the `Signed-off-by:` lines except for self (use 'self' for that). - 'misc-by' will avoid including anyone mentioned in Acked-by, Reviewed-by, Tested-by and other "-by" lines in the patch body,
Documentation/githooks.txt +1 -1
@@ -164,7 +164,7 @@ can also be used to refuse the commit after inspecting the message file. The default 'commit-msg' hook, when enabled, detects duplicate -"Signed-off-by" lines, and aborts the commit if one is found. +`Signed-off-by:` lines, and aborts the commit if one is found. post-commit ~~~~~~~~~~~
Documentation/merge-options.txt +2 -2
@@ -79,7 +79,7 @@ actual commits being merged. --signoff:: --no-signoff:: - Add Signed-off-by line by the committer at the end of the commit + Add a `Signed-off-by:` line by the committer at the end of the commit log message. The meaning of a signoff depends on the project to which you're committing. For example, it may certify that the committer has the rights to submit the work under the project's license or agrees to
@@ -89,7 +89,7 @@ actual commits being merged. leadership of the project to which you're contributing to understand how the signoffs are used in that project. + -With --no-signoff do not add a Signed-off-by line. +With --no-signoff do not add a `Signed-off-by:` line. --stat:: -n::
builtin/am.c +1 -1
@@ -2237,7 +2237,7 @@ int cmd_am(int argc, const char **argv, const char *prefix) N_("allow fall back on 3way merging if needed")),OPT__QUIET (&state.quiet,N_ ("be quiet" )),OPT_SET_INT ('s' ,"signoff" , &state.signoff, -N_ ("add a Signed-off-by line to the commit message" ), +N_ ("add a Signed-off-by: line to the commit message" ),SIGNOFF_EXPLICIT ),OPT_BOOL ('u' ,"utf8" , &state.utf8, N_("recode into utf8 (default)")),
builtin/commit.c +1 -1
@@ -1507,7 +1507,7 @@ int cmd_commit(int argc, const char **argv, const char *prefix)OPT_STRING (0 ,"fixup" , &fixup_message,N_ ("commit" ),N_ ("use autosquash formatted message to fixup specified commit" )),OPT_STRING (0 ,"squash" , &squash_message,N_ ("commit" ),N_ ("use autosquash formatted message to squash specified commit" )),OPT_BOOL (0 ,"reset-author" , &renew_authorship,N_ ("the commit is authored by me now (used with -C/-c/--amend)" )), -OPT_BOOL ('s' ,"signoff" , &signoff,N_ ("add Signed-off-by:" )), +OPT_BOOL ('s' ,"signoff" , &signoff,N_ ("add a Signed-off-by: line" )),OPT_FILENAME ('t' ,"template" , &template_file,N_ ("use specified template file" )),OPT_BOOL ('e' ,"edit" , &edit_flag,N_ ("force edit of commit" )), OPT_CLEANUP(&cleanup_arg),
builtin/log.c +1 -1
@@ -1738,7 +1738,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)OPT_CALLBACK_F ('N' ,"no-numbered" , &numbered,NULL ,N_ ("use [PATCH] even with multiple patches" ),PARSE_OPT_NOARG |PARSE_OPT_NONEG , no_numbered_callback), -OPT_BOOL ('s' ,"signoff" , &do_signoff,N_ ("add Signed-off-by:" )), +OPT_BOOL ('s' ,"signoff" , &do_signoff,N_ ("add a Signed-off-by: line" )),OPT_BOOL (0 ,"stdout" , &use_stdout,N_ ("print patches to standard out" )), OPT_BOOL(0, "cover-letter", &cover_letter,
builtin/merge.c +1 -1
@@ -289,7 +289,7 @@ static struct option builtin_merge_options[] = { N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, OPT_AUTOSTASH(&autostash), OPT_BOOL(0, "overwrite-ignore", &overwrite_ignore, N_("update ignored files (default)")), - OPT_BOOL(0, "signoff", &signoff, N_("add Signed-off-by:")), + OPT_BOOL(0, "signoff", &signoff, N_("add a Signed-off-by: line")), OPT_BOOL(0, "no-verify", &no_verify, N_("bypass pre-merge-commit and commit-msg hooks")),OPT_END () };
builtin/pull.c +1 -1
@@ -142,7 +142,7 @@ static struct option pull_options[] = { N_("add (at most <n>) entries from shortlog to merge commit message"), PARSE_OPT_OPTARG),OPT_PASSTHRU (0 ,"signoff" , &opt_signoff,NULL , -N_ ("add Signed-off-by:" ), +N_ ("add a Signed-off-by: line" ),PARSE_OPT_OPTARG ), OPT_PASSTHRU(0, "squash", &opt_squash, NULL, N_("create a single commit instead of doing a merge"),
builtin/revert.c +1 -1
@@ -107,7 +107,7 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts)OPT_BOOL ('n' ,"no-commit" , &opts->no_commit,N_ ("don't automatically commit" )),OPT_BOOL ('e' ,"edit" , &opts->edit,N_ ("edit the commit message" )),OPT_NOOP_NOARG ('r' ,NULL ), -OPT_BOOL ('s' ,"signoff" , &opts->signoff,N_ ("add Signed-off-by:" )), +OPT_BOOL ('s' ,"signoff" , &opts->signoff,N_ ("add a Signed-off-by: line" )),OPT_CALLBACK ('m' ,"mainline" , opts,N_ ("parent-number" ),N_ ("select mainline parent" ), option_parse_m), OPT_RERERE_AUTOUPDATE(&opts->allow_rerere_auto),
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v2 2/3] Documentation: stylistically normalize references to Signed-off-by:
Hi Bradley,
I think that the 3-patch series that Junio was talking about in [1] is actually this one [2].
Skimming the differences between the two, this patch of yours doesn't have an analogue in what Junio sent. But, I think it's worthwhile, so perhaps it could be applied on top before moving into next (at the time of writing, this is integrated into 'seen' as 1b98087e0f (Merge branch 'bk/sob-dco' into jch, 2020-10-19)).
Quoted 10 lines · Bradley M. Kuhn
Ted reported during patch review of the previous commit that an old typo was present in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article.
[...]
Reported-by "Theodore Y. Ts'o" <[email protected]>Message-ID: <[email protected]>
Signed-off-by Bradley M. Kuhn <[email protected]>
Thanks,
Taylor
[1]: https://lore.kernel.org/git/[email protected]/
[2]: https://lore.kernel.org/git/[email protected]/
Re: [PATCH v2 2/3] Documentation: stylistically normalize references to Signed-off-by:
Quoted 5 lines · Taylor Blau
I think that the 3-patch series that Junio was talking about in [1] is actually this one [2].
...
[1]: https://lore.kernel.org/git/[email protected]/
[2]: https://lore.kernel.org/git/[email protected]/
True.
I actually think it is a bad idea to add ":" after every mention of "Signed-off-by"; it only looks clarifying because we use a boring and generic word "line" to refer to where that three-word token appears.
We can say "a 'Signed-off-by' trailer" and it becomes plenty clear that we are not talking about any random line in the log message, and we do not need ":" everywhere, I suspect.
Thanks.
v3 cover clarify meaning of --signoff & related doc improvements in describing Signed-off-by
[ Note that there were competing v2's of this patch series, one from me and
one from Junio. Sorry about that; I had missed Junio's from Sunday. ]
I believe this patch series now addresses all the issues raised in the discussion.
* [1/4] is unchanged from Junio's v2 and is the preparatory cleanup.
* [2/4] remains unchanged textually since I originally posted it and Pfeff signed off.
* [3/4] is unchanged from Junio's v2 and is his clarification for what
Git's --signoff means.
* [4/4] is a rework of a patch from *my* v2. It takes into account Junio's comments about preferring the word "trailer" and leaving off the ':' whenever possible when discussing Signed-off-by.
For reference:
v1: https://lore.kernel.org/git/[email protected]/ Junio's v2: https://lore.kernel.org/git/[email protected]/ my v2: https://lore.kernel.org/git/[email protected]/
Bradley M. Kuhn (2):
Documentation: clarify and expand description of --signoff
Documentation: stylistically normalize references to Signed-off-by:
Junio C Hamano (2):
doc: preparatory clean-up of description on the sign-off option
SubmittingPatches: clarify DCO is our --signoff rule
Documentation/MyFirstContribution.txt | 2 +- Documentation/SubmittingPatches | 35 +++++++++++++++------------ Documentation/config/format.txt | 2 +- Documentation/git-am.txt | 2 +- Documentation/git-cherry-pick.txt | 2 +- Documentation/git-commit.txt | 10 ++------ Documentation/git-format-patch.txt | 2 +- Documentation/git-rebase.txt | 2 +- Documentation/git-revert.txt | 2 +- Documentation/git-send-email.txt | 4 +-- Documentation/git-svn.txt | 4 +-- Documentation/githooks.txt | 2 +- Documentation/merge-options.txt | 11 +-------- Documentation/signoff-option.txt | 18 ++++++++++++++ builtin/am.c | 2 +- builtin/commit.c | 2 +- builtin/log.c | 2 +- builtin/merge.c | 2 +- builtin/pull.c | 2 +- builtin/rebase.c | 2 +- builtin/revert.c | 2 +- commit.c | 2 +- 22 files changed, 60 insertions(+), 54 deletions(-) create mode 100644 Documentation/signoff-option.txt
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
PATCH v3 1/4 doc: preparatory clean-up of description on the sign-off option
From: Junio C Hamano <[email protected]>
Almost identical text on the signed-off-by trailer appears in the documentation for "git commit" and "git merge" and its friends.
Introduce a new signoff-options.txt file to be shared. A couple things of note are:
- The short-form "-s" is available only in "git commit", but not in commands that are friends of "git merge", as it is used as a short-hand for "--strategy".
- The original lacks description on the negated "--no-signoff" form on "git commit" side, but it equally is applicable. It however was unclear in the original text that not adding a Signed-off-by trailer is the default, so rephrase to explain it as a way to countermand a --signoff option that appeared earlier on the same command line.
This is in preparation to apply a further clarification on what exactly the Signed-off-by trailer means.
--- Documentation/git-commit.txt | 10 ++-------- Documentation/merge-options.txt | 11 +---------- Documentation/signoff-option.txt | 14 ++++++++++++++ 3 files changed, 17 insertions(+), 18 deletions(-) create mode 100644 Documentation/signoff-option.txt
Documentation/git-commit.txt +2 -8
@@ -59,6 +59,7 @@ commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after that, you can recover from it with 'git reset'. +:git-commit: 1 OPTIONS -------
@@ -163,14 +164,7 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. message, the commit is aborted. This has no effect when a message is given by other means, e.g. with the `-m` or `-F` options. --s:: ---signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). +include::signoff-option.txt[] -n:: --no-verify::
Documentation/merge-options.txt +1 -10
@@ -77,16 +77,7 @@ When not possible, refuse to merge and exit with a non-zero status. With --no-log do not list one-line descriptions from the actual commits being merged. ---signoff:: ---no-signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). -+ -With --no-signoff do not add a Signed-off-by line. +include::signoff-option.txt[] --stat:: -n::
Documentation/signoff-option.txt new file +14 -0
@@ -0,0 +1,14 @@ +ifdef::git-commit[] +-s:: +endif::git-commit[] +--signoff:: +--no-signoff:: + Add Signed-off-by line by the committer at the end of the commit + log message. The meaning of a signoff depends on the project, + but it typically certifies that committer has + the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin + (see http://developercertificate.org/ for more information). ++ +The --no-signoff option can be used to countermand an earlier --signoff +option on the command line.
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
PATCH v3 2/4 Documentation: clarify and expand description of --signoff
In reply to Bradley M. KuhnBuilding on past documentation improvements in b2c150d3aa (Expand documentation describing --signoff, 2016-01-05), further clarify that any project using Git may and often does set its own policy.
However, leave intact reference to the Linux DCO, which Git also uses. It is reasonable for Git to advocate for its own Signed-off-by methodology in its documentation, as long as the documentation remains respectful that YMMV and other projects may well have very different contributor representations tied to Signed-off-by.
--- Documentation/signoff-option.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-)
Documentation/signoff-option.txt +10 -6
@@ -3,12 +3,16 @@ ifdef::git-commit[] endif::git-commit[] --signoff:: --no-signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). + Add a Signed-off-by trailer by the committer at the end of the commit + log message. The meaning of a signoff depends on the project + to which you're committing. For example, it may certify that + the committer has the rights to submit the work under the + project's license or agrees to some contributor representation, + such as a Developer Certificate of Origin. + (See http://developercertificate.org for the one used by the + Linux kernel and Git projects.) Consult the documentation or + leadership of the project to which you're contributing to + understand how the signoffs are used in that project. + The --no-signoff option can be used to countermand an earlier --signoff option on the command line.
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v3 2/4] Documentation: clarify and expand description of --signoff
Junio,
Junio wrote in the sub-thread about [PATCH v3 4/4]:
Quoted 2 lines
Quoted 2 lines
It seems the patches [1-3/4] are identical to what has been queued in 'seen', which is a good sign.
One change I made in v3 patchset was to add Peff's Signed-off-by, as it is *not* there in commit 04c2b9ebd0 in seen:
I wrote in [PATCH v3 2/4]:
Quoted 1 line
Signed-off-by Jeff King <[email protected]>
… given that Peff made edits to this before it was posted, I think we want to be sure Peff's Signed-off-by is included. It just seems like the "right thing" to get the Signed-off-by trailers 100% correct on a commit that changes the description of Signed-off-by. 😆
I wrote in [PATCH v3 2/4]:
Quoted 1 line
Reviewed-by Taylor Blau <[email protected]>
I doubt Taylor cares whether this Reviewed-by trailer makes it in, but I did add that too based on Taylor providing it earlier in the discussion of this patch. ☺
--
Bradley M. Kuhn - he/him
Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v3 2/4] Documentation: clarify and expand description of --signoff
Quoted 5 lines · Bradley M. Kuhn
Quoted 1 line
Reviewed-by Taylor Blau <[email protected]>I doubt Taylor cares whether this Reviewed-by trailer makes it in, but I did add that too based on Taylor providing it earlier in the discussion of this patch. ☺
He doesn't ;-).
Thanks,
Taylor
PATCH v3 3/4 SubmittingPatches: clarify DCO is our --signoff rule
In reply to Bradley M. KuhnFrom: Junio C Hamano <[email protected]>
The description on sign-off and DCO was written back in the days where there was only a choice between "use sign-off and it means the contributor agrees to the Linux-kernel style DCO" and "not using sign-off at all will make your patch unusable". These days, we are trying to clarify that the exact meaning of a sign-off varies project to project.
Let's be more explicit when presenting what _our_ rules are. It is of secondary importance that it originally came from the kernel project, so move the description as a historical note at the end, while cautioning that what a sign-off means to us may be different from what it means to other projects contributors may have been used to.
--- Documentation/SubmittingPatches | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-)
Documentation/SubmittingPatches +14 -11
@@ -300,15 +300,12 @@ patch. [[sign-off]] === Certify your work by adding your "Signed-off-by: " line -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although core Git is a lot -smaller project it is a good discipline to follow it. +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. -The sign-off is a simple line at the end of the explanation for -the patch, which certifies that you wrote it or otherwise have -the right to pass it on as an open-source patch. The rules are -pretty simple: if you can certify the below D-C-O: +If you can certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1
@@ -338,14 +335,15 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -then you just add a line saying +you add a "Signed-off-by" trailer to your commit, that looks like +this: .... Signed-off-by: Random J Developer <[email protected]> .... -This line can be automatically added by Git if you run the git-commit -command with the -s option. +This line can be added by Git if you run the git-commit command with +the -s option. Notice that you can place your own Signed-off-by: line when forwarding somebody else's patch with the above rules for
@@ -353,6 +351,11 @@ 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). +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 +from that of the project you are accustomed to. + [[real-name]] Also notice that a real name is used in the Signed-off-by: line. Please don't hide your real name.
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
PATCH v3 4/4 Documentation: stylistically normalize references to Signed-off-by:
In reply to Bradley M. KuhnTed reported an old typo in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article.
Upon examination, it seems that the documentation (including items in Documentation/, but also option help strings) have been quite inconsistent on usage when referring to Signed-off-by.
First, very few places used a definite or indefinite article with the phrase "Signed-off-by line", but that was the initial typo that led to this investigation. So, normalize using either an indefinite or definite article consistently.
The original phrasing, in Commit 3f971fc425b (Documentation updates, 2005-08-14), is "Add Signed-off-by line". Commit 6f855371a53 (Add --signoff, --check, and long option-names. 2005-12-09) switched to using "Add Signed-off-by: line", but didn't normalize the former commit to match. Later commits seem to have cut and pasted from one or the other, which is likely how the usage became so inconsistent.
Junio stated on the git mailing list in <[email protected]> a preference to leave off the colon. Thus, prefer Signed-off-by (with backticks) for the documentation files and Signed-off-by (without backticks) for option help strings.
Additionally, Junio argued that "trailer" is now the standard term to refer to Signed-off-by, saying that "becomes plenty clear that we are not talking about any random line in the log message". As such, prefer "trailer" over "line" anywhere the former word fits.
However, leave alone those few places in documentation that use Signed-off-by to refer to the process (rather than the specific trailer), or in places where mail headers are generally discussed in comparison with Signed-off-by.
--- Documentation/MyFirstContribution.txt | 2 +- Documentation/SubmittingPatches | 10 +++++----- Documentation/config/format.txt | 2 +- Documentation/git-am.txt | 2 +- Documentation/git-cherry-pick.txt | 2 +- Documentation/git-format-patch.txt | 2 +- Documentation/git-rebase.txt | 2 +- Documentation/git-revert.txt | 2 +- Documentation/git-send-email.txt | 4 ++-- Documentation/git-svn.txt | 4 ++-- Documentation/githooks.txt | 2 +- Documentation/signoff-option.txt | 2 +- builtin/am.c | 2 +- builtin/commit.c | 2 +- builtin/log.c | 2 +- builtin/merge.c | 2 +- builtin/pull.c | 2 +- builtin/rebase.c | 2 +- builtin/revert.c | 2 +- commit.c | 2 +- 20 files changed, 26 insertions(+), 26 deletions(-)
Documentation/MyFirstContribution.txt +1 -1
@@ -249,7 +249,7 @@ component you're working on, followed by a blank line (always required) and then the body of your commit message, which should provide the bulk of the context. Remember to be explicit and provide the "Why" of your change, especially if it couldn't easily be understood from your diff. When editing your commit message, -don't remove the Signed-off-by line which was added by `-s` above. +don't remove the `Signed-off-by` trailer which was added by `-s` above. ---- psuh: add a built-in by popular demand
Documentation/SubmittingPatches +5 -5
@@ -209,7 +209,7 @@ send them as replies to either an additional "cover letter" message (see below), the first patch, or the respective preceding patch. If your log message (including your name on the -Signed-off-by line) is not writable in ASCII, make sure that +`Signed-off-by` trailer) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap
@@ -229,7 +229,7 @@ previously sent. The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the -Signed-off-by: lines, and a line that consists of three dashes, +`Signed-off-by` trailers, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit
@@ -298,7 +298,7 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and patch. [[sign-off]] -=== Certify your work by adding your "Signed-off-by: " line +=== Certify your work by adding your `Signed-off-by` trailer To improve tracking of who did what, we ask you to certify that you wrote the patch or have the right to pass it on under the same license
@@ -345,7 +345,7 @@ this: This line can be added by Git if you run the git-commit command with the -s option. -Notice that you can place your own Signed-off-by: line when +Notice that you can place your own `Signed-off-by` trailer when forwarding somebody else's patch with the above rules for 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
@@ -357,7 +357,7 @@ your patch differs from project to project, so it may be different from that of the project you are accustomed to. [[real-name]] -Also notice that a real name is used in the Signed-off-by: line. Please +Also notice that a real name is used in the `Signed-off-by` trailer. Please don't hide your real name. [[commit-trailers]]
Documentation/config/format.txt +1 -1
@@ -79,7 +79,7 @@ format.thread:: format.signOff:: A boolean value which lets you enable the `-s/--signoff` option of - format-patch by default. *Note:* Adding the Signed-off-by: line to a + format-patch by default. *Note:* Adding the `Signed-off-by` trailer to a patch should be a conscious act and means that you certify you have the rights to submit this work under the same open source license. Please see the 'SubmittingPatches' document for further discussion.
Documentation/git-am.txt +1 -1
@@ -33,7 +33,7 @@ OPTIONS -s:: --signoff:: - Add a `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by` trailer to the commit message, using the committer identity of yourself. See the signoff option in linkgit:git-commit[1] for more information.
Documentation/git-cherry-pick.txt +1 -1
@@ -104,7 +104,7 @@ effect to your index in a row. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add a `Signed-off-by` trailer at the end of the commit message. See the signoff option in linkgit:git-commit[1] for more information. -S[<keyid>]::
Documentation/git-format-patch.txt +1 -1
@@ -119,7 +119,7 @@ include::diff-options.txt[] -s:: --signoff:: - Add `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by` trailer to the commit message, using the committer identity of yourself. See the signoff option in linkgit:git-commit[1] for more information.
Documentation/git-rebase.txt +1 -1
@@ -496,7 +496,7 @@ See also INCOMPATIBLE OPTIONS below. See also INCOMPATIBLE OPTIONS below. --signoff:: - Add a Signed-off-by: trailer to all the rebased commits. Note + Add a `Signed-off-by` trailer to all the rebased commits. Note that if `--interactive` is given then only commits marked to be picked, edited or reworded will have the trailer added. +
Documentation/git-revert.txt +1 -1
@@ -99,7 +99,7 @@ effect to your index in a row. -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add a `Signed-off-by` trailer at the end of the commit message. See the signoff option in linkgit:git-commit[1] for more information. --strategy=<strategy>::
Documentation/git-send-email.txt +2 -2
@@ -313,7 +313,7 @@ Automating the value of `sendemail.identity`. --[no-]signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the + If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the cc list. Default is the value of `sendemail.signedoffbycc` configuration value; if that is unspecified, default to --signed-off-by-cc.
@@ -340,7 +340,7 @@ Automating except for self (use 'self' for that). - 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). -- 'sob' will avoid including anyone mentioned in Signed-off-by lines except +- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except for self (use 'self' for that). - 'misc-by' will avoid including anyone mentioned in Acked-by, Reviewed-by, Tested-by and other "-by" lines in the patch body,
Documentation/git-svn.txt +2 -2
@@ -701,7 +701,7 @@ creating the branch or tag. --use-log-author:: When retrieving svn commits into Git (as part of 'fetch', 'rebase', or - 'dcommit' operations), look for the first `From:` or `Signed-off-by:` line + 'dcommit' operations), look for the first `From:` line or `Signed-off-by` trailer in the log message and use that as the author string. + [verse]
@@ -710,7 +710,7 @@ config key: svn.useLogAuthor --add-author-from:: When committing to svn from Git (as part of 'set-tree' or 'dcommit' operations), if the existing log message doesn't already have a - `From:` or `Signed-off-by:` line, append a `From:` line based on the + `From:` or `Signed-off-by` trailer, append a `From:` line based on the Git commit's author string. If you use this, then `--use-log-author` will retrieve a valid author string for all commits. +
Documentation/githooks.txt +1 -1
@@ -164,7 +164,7 @@ can also be used to refuse the commit after inspecting the message file. The default 'commit-msg' hook, when enabled, detects duplicate -"Signed-off-by" lines, and aborts the commit if one is found. +`Signed-off-by` trailers, and aborts the commit if one is found. post-commit ~~~~~~~~~~~
Documentation/signoff-option.txt +1 -1
@@ -3,7 +3,7 @@ ifdef::git-commit[] endif::git-commit[] --signoff:: --no-signoff:: - Add a Signed-off-by trailer by the committer at the end of the commit + Add a `Signed-off-by` trailer by the committer at the end of the commit log message. The meaning of a signoff depends on the project to which you're committing. For example, it may certify that the committer has the rights to submit the work under the
builtin/am.c +1 -1
@@ -2237,7 +2237,7 @@ int cmd_am(int argc, const char **argv, const char *prefix) N_("allow fall back on 3way merging if needed")),OPT__QUIET (&state.quiet,N_ ("be quiet" )),OPT_SET_INT ('s' ,"signoff" , &state.signoff, -N_ ("add a Signed-off-by line to the commit message" ), +N_ ("add a Signed-off-by trailer to the commit message" ),SIGNOFF_EXPLICIT ),OPT_BOOL ('u' ,"utf8" , &state.utf8, N_("recode into utf8 (default)")),
builtin/commit.c +1 -1
@@ -1507,7 +1507,7 @@ int cmd_commit(int argc, const char **argv, const char *prefix)OPT_STRING (0 ,"fixup" , &fixup_message,N_ ("commit" ),N_ ("use autosquash formatted message to fixup specified commit" )),OPT_STRING (0 ,"squash" , &squash_message,N_ ("commit" ),N_ ("use autosquash formatted message to squash specified commit" )),OPT_BOOL (0 ,"reset-author" , &renew_authorship,N_ ("the commit is authored by me now (used with -C/-c/--amend)" )), -OPT_BOOL ('s' ,"signoff" , &signoff,N_ ("add Signed-off-by:" )), +OPT_BOOL ('s' ,"signoff" , &signoff,N_ ("add a Signed-off-by trailer" )),OPT_FILENAME ('t' ,"template" , &template_file,N_ ("use specified template file" )),OPT_BOOL ('e' ,"edit" , &edit_flag,N_ ("force edit of commit" )), OPT_CLEANUP(&cleanup_arg),
builtin/log.c +1 -1
@@ -1738,7 +1738,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)OPT_CALLBACK_F ('N' ,"no-numbered" , &numbered,NULL ,N_ ("use [PATCH] even with multiple patches" ),PARSE_OPT_NOARG |PARSE_OPT_NONEG , no_numbered_callback), -OPT_BOOL ('s' ,"signoff" , &do_signoff,N_ ("add Signed-off-by:" )), +OPT_BOOL ('s' ,"signoff" , &do_signoff,N_ ("add a Signed-off-by trailer" )),OPT_BOOL (0 ,"stdout" , &use_stdout,N_ ("print patches to standard out" )), OPT_BOOL(0, "cover-letter", &cover_letter,
builtin/merge.c +1 -1
@@ -289,7 +289,7 @@ static struct option builtin_merge_options[] = { N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" }, OPT_AUTOSTASH(&autostash), OPT_BOOL(0, "overwrite-ignore", &overwrite_ignore, N_("update ignored files (default)")), - OPT_BOOL(0, "signoff", &signoff, N_("add Signed-off-by:")), + OPT_BOOL(0, "signoff", &signoff, N_("add a Signed-off-by trailer")), OPT_BOOL(0, "no-verify", &no_verify, N_("bypass pre-merge-commit and commit-msg hooks")),OPT_END () };
builtin/pull.c +1 -1
@@ -142,7 +142,7 @@ static struct option pull_options[] = { N_("add (at most <n>) entries from shortlog to merge commit message"), PARSE_OPT_OPTARG),OPT_PASSTHRU (0 ,"signoff" , &opt_signoff,NULL , -N_ ("add Signed-off-by:" ), +N_ ("add a Signed-off-by trailer" ),PARSE_OPT_OPTARG ), OPT_PASSTHRU(0, "squash", &opt_squash, NULL, N_("create a single commit instead of doing a merge"),
builtin/rebase.c +1 -1
@@ -1324,7 +1324,7 @@ int cmd_rebase(int argc, const char **argv, const char *prefix)N_ ("do not show diffstat of what changed upstream" ), PARSE_OPT_NOARG, NULL, REBASE_DIFFSTAT },OPT_BOOL (0 ,"signoff" , &options.signoff, -N_ ("add a Signed-off-by: line to each commit" )), +N_ ("add a Signed-off-by trailer to each commit" )),OPT_BOOL (0 ,"committer-date-is-author-date" , &options.committer_date_is_author_date, N_("make committer date match author date")),
builtin/revert.c +1 -1
@@ -107,7 +107,7 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts)OPT_BOOL ('n' ,"no-commit" , &opts->no_commit,N_ ("don't automatically commit" )),OPT_BOOL ('e' ,"edit" , &opts->edit,N_ ("edit the commit message" )),OPT_NOOP_NOARG ('r' ,NULL ), -OPT_BOOL ('s' ,"signoff" , &opts->signoff,N_ ("add Signed-off-by:" )), +OPT_BOOL ('s' ,"signoff" , &opts->signoff,N_ ("add a Signed-off-by trailer" )),OPT_CALLBACK ('m' ,"mainline" , opts,N_ ("parent-number" ),N_ ("select mainline parent" ), option_parse_m), OPT_RERERE_AUTOUPDATE(&opts->allow_rerere_auto),
commit.c +1 -1
@@ -1586,7 +1586,7 @@ const char *find_commit_header(const char *msg, const char *key, size_t *out_len/* * Inspect the given string and determine the true "end" of the log message, in -* order to find where to put a new Signed-off-by: line. Ignored are +* order to find where to put a new Signed-off-by trailer. Ignored are * trailing comment lines and blank lines. To support "git commit -s * --amend" on an existing commit, we also ignore "Conflicts:". To * support "git commit -v", we truncate at cut lines.
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v3 4/4] Documentation: stylistically normalize references to Signed-off-by:
Quoted 7 lines · Bradley M. Kuhn
Ted reported an old typo in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article.
Upon examination, it seems that the documentation (including items in
Documentation/, but also option help strings) have been quite inconsistent on usage when referring toSigned-off-by.
Thanks. This must have been a lot of proofreading ;-)
It seems the patches [1-3/4] are identical to what has been queued in 'seen', which is a good sign. There was a reversion of a typofix in the log message of one of them, though.
Documentation/git-svn.txt
Quoted 25 lines
Documentation/git-send-email.txt +2
-2@@ -313,7 +313,7 @@ Automating the value of `sendemail.identity`. --[no-]signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the + If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the cc list. Default is the value of `sendemail.signedoffbycc` configuration value; if that is unspecified, default to --signed-off-by-cc.@@ -340,7 +340,7 @@ Automating except for self (use 'self' for that). - 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). -- 'sob' will avoid including anyone mentioned in Signed-off-by lines except +- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except for self (use 'self' for that). - 'misc-by' will avoid including anyone mentioned in Acked-by,Reviewed-by, Tested-by and other "-by" lines in the patch body,
Documentation/git-svn.txt +0
-0
Did you hand edit the second hunk starting at line 340 to git-send-email.txt? I've fixed it up manually, so no need to resend.
Thanks.
Re: [PATCH v3 4/4] Documentation: stylistically normalize references to Signed-off-by:
Quoted 2 lines · Junio C Hamano
Did you hand edit the second hunk starting at line 340 to git-send-email.txt?
I don't think so, although this is only the third time I've used the git format-patch/send-email workflow so it's entirely possible I did something funky …
Quoted 1 line
I've fixed it up manually, so no need to resend.
… but thanks for taking care of it!
--
Bradley M. Kuhn - he/him
Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v3 0/4] clarify meaning of --signoff & related doc improvements in describing Signed-off-by
In reply to Bradley M. KuhnHi Bradley,
Quoted 11 lines · Bradley M. Kuhn
[ Note that there were competing v2's of this patch series, one from me and
one from Junio. Sorry about that; I had missed Junio's from Sunday. ]I believe this patch series now addresses all the issues raised in the discussion.
* [1/4] is unchanged from Junio's v2 and is the preparatory cleanup.
* [2/4] remains unchanged textually since I originally posted it and Pfeff signed off.
Quoted 6 lines
* [3/4] is unchanged from Junio's v2 and is his clarification for what
Git's --signoff means.* [4/4] is a rework of a patch from *my* v2. It takes into account Junio's comments about preferring the word "trailer" and leaving off the ':' whenever possible when discussing Signed-off-by.
Thanks; I think some of our emails crossed over one another, but this version looks good to me.
I'd be happy to discard what's currently in seen (integrated as 1b98087e0f (Merge branch 'bk/sob-dco' into jch, 2020-10-19 at the time of writing) in favor of what's here.
Thanks,
Taylor
Re: [PATCH v3 0/4] clarify meaning of --signoff & related doc improvements in describing Signed-off-by
Quoted 2 lines · Taylor Blau
Thanks; I think some of our emails crossed over one another, but this version looks good to me.
Yes, I was preparing the patch when you wrote that you disagreed with Junio and preferred the ":".
FWIW, I left the ":" anywhere headers were being discussed and those headers were described with ":"s on them. I only changed places where "Signed-off-by:" stood alone.
Before my v3 patchset, usage was inconsistent about (roughly half/half), so the decision is mostly a coin toss. I didn't have a strong opinion when I was first writing the v3 patchset, but having thought about it overnight, I now think leaving the ":" *out* is better because a reader new to Git is more likely to think a ":" is punctuation, rather than being part of a moniker. Thus, IMO, leaving out the ":" in most cases probably improves readability.
The remainder of this email is purely an edification question that may help serve to improve Documentation/SubmittingPatches:
Quoted 3 lines
I'd be happy to discard what's currently in seen (integrated as
1b98087e0f(Merge branch 'bk/sob-dco' into jch, 2020-10-19 at the time of writing) in favor of what's here.
I wasn't sure what I should be doing with the patch set once it was already in 'seen'. The only two references in SubmittingPatches I could find were:
From Documentation/SubmittingPatches:
Quoted 4 lines
Quoted 4 lines
In any time between the (2)-(3) cycle, the maintainer may pick it up from the list and queue it to
seen, in order to make it easier for people play with it without having to pick up and apply the patch to their trees themselves.
and
Quoted 4 lines
Quoted 4 lines
git pull --rebasewill automatically skip already-applied patches, and will let you know. This works only if you rebase on top of the branch in which your patch has been merged (i.e. it will not tell you if your patch is merged inseenif you rebase on top of master).
The former hints that you *shouldn't* change the workflow if some of your patchset is in seen, and the latter hints that maybe you should, but neither section tells you what to do differently, if anything, once your patches are in seen.
I'm curious to know if I went wrong somewhere and the workflow and would be glad to propose another patch to improve SubmittingPatches with a section of what to do when patches show up in seen, but since I'm a n00b (at least as an upstream Git contributor :), I'd need to know how to DTRT in this case to do that.
--
Bradley M. Kuhn - he/him
Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v3 0/4] clarify meaning of --signoff & related doc improvements in describing Signed-off-by
Hi Bradley,
Quoted 9 lines · Bradley M. Kuhn
The remainder of this email is purely an edification question that may help serve to improve
Documentation/SubmittingPatches:Quoted 3 lines
I'd be happy to discard what's currently in seen (integrated as
1b98087e0f(Merge branch 'bk/sob-dco' into jch, 2020-10-19 at the time of writing) in favor of what's here.I wasn't sure what I should be doing with the patch set once it was already in 'seen'. The only two references in SubmittingPatches I could find were:
The conclusive answer is that you can do anything you want when the patches are in 'seen', but when it is in 'next', things have solidified and the series is not meant to be changed. The one exception to that rule is immediately after a release, in which case 'next' is rewound (and thus some topics can be ejected from next).
Quoted 13 lines
From
Documentation/SubmittingPatches:Quoted 4 lines
Quoted 4 lines
In any time between the (2)-(3) cycle, the maintainer may pick it up from the list and queue it to
seen, in order to make it easier for people play with it without having to pick up and apply the patch to their trees themselves.and
Quoted 4 lines
Quoted 4 lines
git pull --rebasewill automatically skip already-applied patches, and will let you know. This works only if you rebase on top of the branch in which your patch has been merged (i.e. it will not tell you if your patch is merged inseenif you rebase on top of master).
Quoted 4 lines
The former hints that you *shouldn't* change the workflow if some of your patchset is in
seen, and the latter hints that maybe you should, but neither section tells you what to do differently, if anything, once your patches are inseen.
I think the latter is really only talking about branches based on 'master' (of course, the same thing is true of branches based on any branch, but it's uncommon to base topics off of 'seen').
The former is saying that 'seen' may change zero, one, or multiple times during the lifetime of a topic. The latter says if you track upstream's 'master' and then 'git pull --rebase', 'git rebase' will tell you if your patches are already applied upstream (in which case you can drop them).
Quoted 5 lines
I'm curious to know if I went wrong somewhere and the workflow and would be glad to propose another patch to improve SubmittingPatches with a section of what to do when patches show up in
seen, but since I'm a n00b (at least as an upstream Git contributor :), I'd need to know how to DTRT in this case to do that.
It couldn't hurt to add something to the effect of:
Since 'seen' is a convenience branch that contains the current state of the in-flight topics, it is subject to be changed and rebuilt multiple times (c.f., link:howto/maintain-git) so the presence of your patches in 'seen' (but not 'next' or 'master') should not affect your workflow.
Thanks,
Taylor
Re: [PATCH v3 0/4] clarify meaning of --signoff & related doc improvements in describing Signed-off-by
In reply to Bradley M. KuhnQuoted 2 lines · Bradley M. Kuhn
I wasn't sure what I should be doing with the patch set once it was already in 'seen'. The only two references in SubmittingPatches I could find were:
Being 'seen' is an indication that it has been seen and does not mean anything more than that. It is appreciated that a topic in such a state is improved by replacing.
Quoted 5 lines
From
Documentation/SubmittingPatches:Quoted 4 lines
Quoted 4 lines
In any time between the (2)-(3) cycle, the maintainer may pick it up from the list and queue it to
seen, in order to make it easier for people play with it without having to pick up and apply the patch to their trees themselves.
Yes. Other people then can "git fetch" from me and follow the first parent chain "git log --first-parent origin/master..origin/seen" to find the tip of your topic, instead of finding your message in the list archive and running "git am" themselves.
The original submitter/owner of the topic can also find the tip of the topic _in_ my tree the same way as others and reset their branch to what is queued in 'seen' if they wanted to keep minor fixes I made based on review comments while applying the e-mailed patches.
Then they can further work on polishing the topic with the usual means, e.g. using "rebase -i", and finally "format-patch" to send out a new round. Being or not being in 'seen' does not change the workflow that much.
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
git pull --rebasewill automatically skip already-applied patches, and will let you know. This works only if you rebase on top of the branch in which your patch has been merged (i.e. it will not tell you if your patch is merged inseenif you rebase on top of master).
This is talking about a fairly mature topic that has already been in 'next' and was on the course to graduate to 'master'. The topic would eventually be in 'master', and at that point "pull --rebase" would notice that the patches are no longer needed (or were merged in a different form). But that does not apply to topics that are not in 'master' yet.
Where the workflow changes is when the topic hits 'next'. After that, we request you to give incremental updates to refine what is queued already.
The reasoning behind this is simple and arbitrary. It often is the case that keeping mistakes in early iterations, and fixes to these mistakes, recorded in history is not worth the attention of future readers of "git log" who need to study the history, assuming that trivial mistakes are caught early. Once earlier rounds of review is done and everybody is more or less happy, the topic gets merged to 'next', and after that point, a new issue that gets noticed and fixed _are_ worth recording in history, because both the original contributor and reviewers failed to catch such glitches.
Quoted 5 lines
I'm curious to know if I went wrong somewhere and the workflow and would be glad to propose another patch to improve SubmittingPatches with a section of what to do when patches show up in
seen, but since I'm a n00b (at least as an upstream Git contributor :), I'd need to know how to DTRT in this case to do that.
I thought your v3 did things perfectly.
Thanks.
Re: [PATCH v3 0/4] clarify meaning of --signoff & related doc improvements in describing Signed-off-by
Quoted 3 lines
Quoted 2 lines · Bradley M. Kuhn
I wasn't sure what I should be doing with the patch set once it was already in 'seen'.
Quoted 2 lines · Junio C Hamano
Being 'seen' is an indication that it has been seen and does not mean anything more than that.
Documentation/SubmittingPatches says:
Quoted 10 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
git pull --rebasewill automatically skip already-applied patches, and will let you know. This works only if you rebase on top of the branch in which your patch has been merged (i.e. it will not tell you if your patch is merged inseenif you rebase on top of master).This is talking about a fairly mature topic that has already been in 'next' and was on the course to graduate to 'master'. The topic would eventually be in 'master', and at that point "pull --rebase" would notice that the patches are no longer needed (or were merged in a different form). But that does not apply to topics that are not in 'master' yet.
Junio, thanks for your detailed reply. I have a couple ideas of some minor changes to SubmittingPatches that would have made what you said clearer to me when I was doing my first patch. I'll think about it some and send something along, but probably won't get to it until next month (but it doesn't seem urgent).
Quoted 5 lines · Taylor
Quoted 5 lines
Quoted 5 lines
Since 'seen' is a convenience branch that contains the current state
of the in-flight topics, it is subject to be changed and rebuilt multiple times (c.f., link:howto/maintain-git) so the presence of your patches in 'seen' (but not 'next' or 'master') should not affect your workflow.
I'll hold on to this text as a possibility, to start from when I dig into the proposals above. Thanks!
--
Bradley M. Kuhn - he/him
Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter
Re: [PATCH v2 2/3] Documentation: stylistically normalize references to Signed-off-by:
In reply to Junio C HamanoQuoted 10 lines · Junio C Hamano
Quoted 5 lines · Taylor Blau
I think that the 3-patch series that Junio was talking about in [1] is actually this one [2].
...
[1]: https://lore.kernel.org/git/[email protected]/
[2]: https://lore.kernel.org/git/[email protected]/True.
Quoted 8 lines
I actually think it is a bad idea to add ":" after every mention of "Signed-off-by"; it only looks clarifying because we use a boring and generic word "line" to refer to where that three-word token appears.
We can say "a 'Signed-off-by' trailer" and it becomes plenty clear that we are not talking about any random line in the log message, and we do not need ":" everywhere, I suspect.
Mm. I may be in the minority that I think having ":" after "Signed-off-by" is helpful, but I'm happy to go whichever way others find most clear.
Quoted 1 line
Thanks.
Thanks,
Taylor
PATCH v2 3/3 SubmittingPatches: clarify DCO is our --signoff rule
In reply to Bradley M. KuhnFrom: Junio C Hamano <[email protected]>
The description on sign-off and DCO was written back in the days where there was only a choice between "use sign-off and it means the contributor agrees to the Linux-kernel style DCO" and "not using sign-off at all will make your patch unusable". These days, we are trying to clarify that the exact meaning of a sign-off varies project to project.
Let's be more explicit when presenting what _our_ rules are. It is of secondary importance that it originally came from the kernel project, so move the description as a historical note at the end, while cautioning that what a sign-off means to us may be different from what it means to other projects contributors may have been used to.
--- Documentation/SubmittingPatches | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-)
Documentation/SubmittingPatches +14 -11
@@ -300,15 +300,12 @@ patch. [[sign-off]] === Certify your work by adding your `Signed-off-by:` line -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although core Git is a lot -smaller project it is a good discipline to follow it. +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. -The sign-off is a simple line at the end of the explanation for -the patch, which certifies that you wrote it or otherwise have -the right to pass it on as an open-source patch. The rules are -pretty simple: if you can certify the below D-C-O: +If you can certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1
@@ -338,14 +335,15 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -then you just add a line saying +you add a "Signed-off-by" trailer to your commit, that looks like +this: .... Signed-off-by: Random J Developer <[email protected]> .... -This line can be automatically added by Git if you run the git-commit -command with the -s option. +This line can be added by Git if you run the git-commit command with +the -s option. Notice that you can place your own `Signed-off-by:` line when forwarding somebody else's patch with the above rules for
@@ -353,6 +351,11 @@ 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). +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 +from that of the project you are accustomed to. + [[real-name]] Also notice that a real name is used in the `Signed-off-by:` line. Please don't hide your real name.
Signature · 4 lines
Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter
v2 cover Claryfing the meaning of the sign-off
So here is to tie the loose ends, based on inputs to the first round.
* [1/3] is new; this is a preparatory clean-up to dedup two very similar paragraphs in the existing documentation, thanks to the idea by Philippe Blain.
* [2/3] is text taken from Bradley's patch to update the manpages; thanks to the preparatory clean-up, we no longer need to duplicate the new text. Grammofix pointed out by Ted Ts'o has also been applied.
* [3/3] clarifies what sign-off means to _this_ project. This step hasn't changed from what has been queued in 'seen'.
For those who missed the original, it appears at
lore.kernel.org/git/[email protected]
Bradley M. Kuhn (1):
Documentation: clarify and expand description of --signoff
Junio C Hamano (2):
doc: preparatory clean-up of description on the sign-off option
SubmittingPatches: clarify DCO is our --signoff rule
Documentation/SubmittingPatches | 25 ++++++++++++++----------- Documentation/git-commit.txt | 10 ++-------- Documentation/merge-options.txt | 11 +---------- Documentation/signoff-option.txt | 18 ++++++++++++++++++ 4 files changed, 35 insertions(+), 29 deletions(-) create mode 100644 Documentation/signoff-option.txt
PATCH v2 1/3 doc: preparatory clean-up of description on the sign-off option
Almost identical text on the signed-off-by trailer appears in the documentation for "git commit" and "git merge" and its friends.
Introduce a new signoff-options.txt file to be shared. A couple things of note are:
- The short-form "-s" is available only in "git commit", but not in commands that are friends of "git merge", as it is used as a short-hand for "--strategy".
- The original lacks description on the negated "--no-signoff" form on "git commit" side, but it equally is applicable. It however was unclear in the original text that not adding a Signed-off-by trailer is the default, so rephrase to explain it as a way to countermand a --signoff option that appeared earlier on the same command line.
This is in preparation to apply a further clarification on what exactly the Signed-off-by trailer means.
---
* It initially seemed that the update in [v2 2/3] didn't need too many iterations to complete, but it turned out that a preliminary clean-up would make it easier to iterate on the text after all.
Documentation/git-commit.txt | 10 ++-------- Documentation/merge-options.txt | 11 +---------- Documentation/signoff-option.txt | 14 ++++++++++++++ 3 files changed, 17 insertions(+), 18 deletions(-) create mode 100644 Documentation/signoff-option.txt
Documentation/git-commit.txt +2 -8
@@ -59,6 +59,7 @@ commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after that, you can recover from it with 'git reset'. +:git-commit: 1 OPTIONS -------
@@ -163,14 +164,7 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. message, the commit is aborted. This has no effect when a message is given by other means, e.g. with the `-m` or `-F` options. --s:: ---signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). +include::signoff-option.txt[] -n:: --no-verify::
Documentation/merge-options.txt +1 -10
@@ -77,16 +77,7 @@ When not possible, refuse to merge and exit with a non-zero status. With --no-log do not list one-line descriptions from the actual commits being merged. ---signoff:: ---no-signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). -+ -With --no-signoff do not add a Signed-off-by line. +include::signoff-option.txt[] --stat:: -n::
Documentation/signoff-option.txt new file +14 -0
@@ -0,0 +1,14 @@ +ifdef::git-commit[] +-s:: +endif::git-commit[] +--signoff:: +--no-signoff:: + Add Signed-off-by line by the committer at the end of the commit + log message. The meaning of a signoff depends on the project, + but it typically certifies that committer has + the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin + (see http://developercertificate.org/ for more information). ++ +The --no-signoff option can be used to countermand an earlier --signoff +option on the command line.
Signature · 1 line
2.29.0-rc2-130-g9dc1ca14f3
PATCH v2 2/3 Documentation: clarify and expand description of --signoff
In reply to Junio C HamanoFrom: "Bradley M. Kuhn" <[email protected]>
Building on past documentation improvements in b2c150d3aa (Expand documentation describing --signoff, 2016-01-05), further clarify that any project using Git may and often does set its own policy.
However, leave intact reference to the Linux DCO, which Git also uses. It is reasonable for Git to advocate for its own Signed-off-by methodology in its documentation, as long as the documentation remains respectful that YMMV and other projects may well have very different contributor representations tied to Signed-off-by.
--- Documentation/signoff-option.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-)
Documentation/signoff-option.txt +10 -6
@@ -3,12 +3,16 @@ ifdef::git-commit[] endif::git-commit[] --signoff:: --no-signoff:: - Add Signed-off-by line by the committer at the end of the commit - log message. The meaning of a signoff depends on the project, - but it typically certifies that committer has - the rights to submit this work under the same license and - agrees to a Developer Certificate of Origin - (see http://developercertificate.org/ for more information). + Add a Signed-off-by trailer by the committer at the end of the commit + log message. The meaning of a signoff depends on the project + to which you're committing. For example, it may certify that + the committer has the rights to submit the work under the + project's license or agrees to some contributor representation, + such as a Developer Certificate of Origin. + (See http://developercertificate.org for the one used by the + Linux kernel and Git projects.) Consult the documentation or + leadership of the project to which you're contributing to + understand how the signoffs are used in that project. + The --no-signoff option can be used to countermand an earlier --signoff option on the command line.
Signature · 1 line
2.29.0-rc2-130-g9dc1ca14f3
PATCH v2 3/3 SubmittingPatches: clarify DCO is our --signoff rule
In reply to Junio C HamanoThe description on sign-off and DCO was written back in the days where there was only a choice between "use sign-off and it means the contributor agrees to the Linux-kernel style DCO" and "not using sign-off at all will make your patch unusable". These days, we are trying to clarify that the exact meaning of a sign-off varies project to project.
Let's be more explicit when presenting what _our_ rules are. It is of secondary importance that it originally came from the kernel project, so move the description as a historical note at the end, while cautioning that what a sign-off means to us may be different from what it means to other projects contributors may have been used to.
--- Documentation/SubmittingPatches | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-)
Documentation/SubmittingPatches +14 -11
@@ -300,15 +300,12 @@ patch. [[sign-off]] === Certify your work by adding your "Signed-off-by: " line -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although core Git is a lot -smaller project it is a good discipline to follow it. +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. -The sign-off is a simple line at the end of the explanation for -the patch, which certifies that you wrote it or otherwise have -the right to pass it on as an open-source patch. The rules are -pretty simple: if you can certify the below D-C-O: +If you can certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1
@@ -338,14 +335,15 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -then you just add a line saying +you add a "Signed-off-by" trailer to your commit, that looks like +this: .... Signed-off-by: Random J Developer <[email protected]> .... -This line can be automatically added by Git if you run the git-commit -command with the -s option. +This line can be added by Git if you run the git-commit command with +the -s option. Notice that you can place your own Signed-off-by: line when forwarding somebody else's patch with the above rules for
@@ -353,6 +351,11 @@ 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). +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 +from that of the project you are accustomed to. + [[real-name]] Also notice that a real name is used in the Signed-off-by: line. Please don't hide your real name.
Signature · 1 line
2.29.0-rc2-130-g9dc1ca14f3
Re: [PATCH v2 0/3] Claryfing the meaning of the sign-off
In reply to Junio C HamanoHi Junio,
Quoted 2 lines · Junio C Hamano
So here is to tie the loose ends, based on inputs to the first round.
All of this looks very good to me, and I really appreciate 1/3, since it made reviewing 2/3 much easier (the combination of seeing more-or-less the same diff twice combined with the re-wrapping made it tricky to read, at least for me).
Thanks,
Taylor