[PATCH v2 0/3] Claryfing the meaning of the sign-off

STALE2117d

5 messages, 2 authors, 2020-10-18 · open the first message on its own page

[PATCH v2 0/3] Claryfing the meaning of the sign-off

From: Junio C Hamano <hidden>
Date: 2020-10-18 19:49:29

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/20201015215933.96425-1-bkuhn@sfconservancy.org

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

From: Junio C Hamano <hidden>
Date: 2020-10-18 19:49:30

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.

Suggested-by: Philippe Blain <redacted>
Signed-off-by: Junio C Hamano <redacted>
---

 * 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

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index a3baea32ae..17150fa7ea 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt

@@ -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::

diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index 80d4831662..eb0aabd396 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt

@@ -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::

diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.txt
new file mode 100644
index 0000000000..d1c6713774
--- /dev/null
+++ b/Documentation/signoff-option.txt

@@ -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.

-- 
2.29.0-rc2-130-g9dc1ca14f3

[PATCH v2 2/3] Documentation: clarify and expand description of --signoff

From: Junio C Hamano <hidden>
Date: 2020-10-18 19:49:33

From: "Bradley M. Kuhn" <redacted>

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.

Signed-off-by: Bradley M. Kuhn <redacted>
Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/signoff-option.txt | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.txt
index d1c6713774..fbff8dd5be 100644
--- a/Documentation/signoff-option.txt
+++ b/Documentation/signoff-option.txt

@@ -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.

-- 
2.29.0-rc2-130-g9dc1ca14f3

[PATCH v2 3/3] SubmittingPatches: clarify DCO is our --signoff rule

From: Junio C Hamano <hidden>
Date: 2020-10-18 19:50:41

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.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/SubmittingPatches | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 291b61e262..f83a050b35 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches

@@ -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 <random@developer.example.org>
 ....
 
-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.

-- 
2.29.0-rc2-130-g9dc1ca14f3

Re: [PATCH v2 0/3] Claryfing the meaning of the sign-off

From: Taylor Blau <hidden>
Date: 2020-10-18 23:31:49

Hi Junio,

On Sun, Oct 18, 2020 at 12:49:09PM -0700, Junio C Hamano wrote:

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).

  Reviewed-by: Taylor Blau [off-list ref]

Thanks,
Taylor

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help