[PATCH v4] docs: Clarify the usage and sign-off requirements for Co-developed-by

[PATCH v4] docs: Clarify the usage and sign-off requirements for Co-developed-by

[Sean Christopherson]

The documentation for Co-developed-by is a bit light on details, e.g. it
doesn't explicitly state that:

  - Multiple Co-developed-by tags are perfectly acceptable
  - Co-developed-by and Signed-off-by must be paired together
  - SOB ordering should still follow standard sign-off procedure

Lack of explicit direction has resulted in developers taking a variety
of approaches, often lacking any intent whatsoever, e.g. scattering SOBs
willy-nilly, collecting them all at the end or the beginning, etc...
Tweak the wording to make it clear that multiple co-authors are allowed,
and document the expectation that standard sign-off procedures are to
be followed.

The use of "original author" has also led to confusion as many patches
don't have just one "original" author, e.g. when multiple developers
are involved from the genesis of the patch.  Remove all usage of
"original" and instead call out that Co-developed-by is simply a way to
provide attribution in addition to the From tag, i.e. neither tag is
intended to imply anything with regard to who did what.

Provide examples to (hopefully) eliminate any ambiguity.

Cc: Tobin C. Harding <me@tobin.cc>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Jorge Ramirez-Ortiz <jorge.ramirez-ortiz@linaro.org>
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: Joe Perches <joe@perches.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Niklas Cassel <niklas.cassel@linaro.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com>
---

v1: https://lkml.kernel.org/r/20190320151140.32432-1-sean.j.christopherson@intel.com
v2: https://lkml.kernel.org/r/20190321184316.8525-1-sean.j.christopherson@intel.com
    Rewrite the blurb to state standard sign-off procedure should be
    followed as opposed to dictating the original author's SOB be last.
v3: https://lkml.kernel.org/r/20190321200103.9333-1-sean.j.christopherson@intel.com
    Update a similar blurb in Documentation/process/5.Posting.rst
v4: Rework the blurbs to avoid use of the word "original" [Tobin]

 Documentation/process/5.Posting.rst          | 10 +++--
 Documentation/process/submitting-patches.rst | 40 +++++++++++++++++---
 2 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index 4213e580f273..d2da09372563 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -216,10 +216,12 @@ The tags in common use are:
    which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
    Code without a proper signoff cannot be merged into the mainline.
 
- - Co-developed-by: states that the patch was also created by another developer
-   along with the original author.  This is useful at times when multiple
-   people work on a single patch.  Note, this person also needs to have a
-   Signed-off-by: line in the patch as well.
+ - Co-developed-by: states that the patch was co-created by several developers;
+   it is a used to give attribution to co-authors (in addition to the author
+   atrributed by the From: tag) when multiple people work on a single patch.
+   Every Co-developed-by: must be immediately followed by a Signed-off-by: of
+   the associated co-author.  Details and examples can be found in
+   :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
 
  - Acked-by: indicates an agreement by another developer (often a
    maintainer of the relevant code) that the patch is appropriate for
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index be7d1829c3af..06db26b12495 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -545,10 +545,40 @@ person it names - but it should indicate that this person was copied on the
 patch.  This tag documents that potentially interested parties
 have been included in the discussion.
 
-A Co-developed-by: states that the patch was also created by another developer
-along with the original author.  This is useful at times when multiple people
-work on a single patch.  Note, this person also needs to have a Signed-off-by:
-line in the patch as well.
+Co-developed-by: states that the patch was co-created by multiple developers;
+it is a used to give attribution to co-authors (in addition to the author
+attributed by the From: tag) when several people work on a single patch.  Since
+Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
+followed by a Signed-off-by: of the associated co-author.  Standard sign-off
+procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
+chronological history of the patch insofar as possible, regardless of whether
+the author is attributed via From: or Co-developed-by:.  Notably, the last
+Signed-off-by: must always be that of the developer submitting the patch.
+
+Note, the From: tag is optional when the From: author is also the person (and
+email) listed in the From: line of the email header.
+
+Example of a patch submitted by the From: author::
+
+	<changelog>
+
+	Co-developed-by: First Co-Author <first@coauthor.example.org>
+	Signed-off-by: First Co-Author <first@coauthor.example.org>
+	Co-developed-by: Second Co-Author <second@coauthor.example.org>
+	Signed-off-by: Second Co-Author <second@coauthor.example.org>
+	Signed-off-by: From Author <from@author.example.org>
+
+Example of a patch submitted by a Co-developed-by: author::
+
+	From: From Author <from@author.example.org>
+
+	<changelog>
+
+	Co-developed-by: Random Co-Author <random@coauthor.example.org>
+	Signed-off-by: Random Co-Author <random@coauthor.example.org>
+	Signed-off-by: From Author <from@author.example.org>
+	Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
+	Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
 
 
 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
@@ -696,7 +726,7 @@ A couple of example Subjects::
 The ``from`` line must be the very first line in the message body,
 and has the form:
 
-        From: Original Author <author@example.com>
+        From: Patch Author <author@example.com>
 
 The ``from`` line specifies who will be credited as the author of the
 patch in the permanent changelog.  If the ``from`` line is missing,
-- 
2.21.0

Re: [PATCH v4] docs: Clarify the usage and sign-off requirements for Co-developed-by

[Joe Perches]

On Fri, 2019-03-22 at 08:57 -0700, Sean Christopherson wrote:
> The documentation for Co-developed-by is a bit light on details, e.g. it
> doesn't explicitly state that:
> 
>   - Multiple Co-developed-by tags are perfectly acceptable
>   - Co-developed-by and Signed-off-by must be paired together
>   - SOB ordering should still follow standard sign-off procedure
> 
> Lack of explicit direction has resulted in developers taking a variety
> of approaches, often lacking any intent whatsoever, e.g. scattering SOBs
> willy-nilly, collecting them all at the end or the beginning, etc...
> Tweak the wording to make it clear that multiple co-authors are allowed,
> and document the expectation that standard sign-off procedures are to
> be followed.
> 
> The use of "original author" has also led to confusion as many patches
> don't have just one "original" author, e.g. when multiple developers
> are involved from the genesis of the patch.  Remove all usage of
> "original" and instead call out that Co-developed-by is simply a way to
> provide attribution in addition to the From tag, i.e. neither tag is
> intended to imply anything with regard to who did what.
> 
> Provide examples to (hopefully) eliminate any ambiguity.

Please add the checkpatch bit to this at the same time.

Re: [PATCH v4] docs: Clarify the usage and sign-off requirements for Co-developed-by

[Sean Christopherson]

On Fri, Mar 22, 2019 at 10:03:07AM -0700, Joe Perches wrote:
> On Fri, 2019-03-22 at 08:57 -0700, Sean Christopherson wrote:
> > The documentation for Co-developed-by is a bit light on details, e.g. it
> > doesn't explicitly state that:
> > 
> >   - Multiple Co-developed-by tags are perfectly acceptable
> >   - Co-developed-by and Signed-off-by must be paired together
> >   - SOB ordering should still follow standard sign-off procedure
> > 
> > Lack of explicit direction has resulted in developers taking a variety
> > of approaches, often lacking any intent whatsoever, e.g. scattering SOBs
> > willy-nilly, collecting them all at the end or the beginning, etc...
> > Tweak the wording to make it clear that multiple co-authors are allowed,
> > and document the expectation that standard sign-off procedures are to
> > be followed.
> > 
> > The use of "original author" has also led to confusion as many patches
> > don't have just one "original" author, e.g. when multiple developers
> > are involved from the genesis of the patch.  Remove all usage of
> > "original" and instead call out that Co-developed-by is simply a way to
> > provide attribution in addition to the From tag, i.e. neither tag is
> > intended to imply anything with regard to who did what.
> > 
> > Provide examples to (hopefully) eliminate any ambiguity.
> 
> Please add the checkpatch bit to this at the same time.

Doh, spaced on that.  I'll wait for additional feedback before sending v5.

Re: [PATCH v4] docs: Clarify the usage and sign-off requirements for Co-developed-by

[Niklas Cassel]

On Fri, Mar 22, 2019 at 08:57:35AM -0700, Sean Christopherson wrote:
> The documentation for Co-developed-by is a bit light on details, e.g. it
> doesn't explicitly state that:
> 
>   - Multiple Co-developed-by tags are perfectly acceptable
>   - Co-developed-by and Signed-off-by must be paired together
>   - SOB ordering should still follow standard sign-off procedure
> 
> Lack of explicit direction has resulted in developers taking a variety
> of approaches, often lacking any intent whatsoever, e.g. scattering SOBs
> willy-nilly, collecting them all at the end or the beginning, etc...
> Tweak the wording to make it clear that multiple co-authors are allowed,
> and document the expectation that standard sign-off procedures are to
> be followed.
> 
> The use of "original author" has also led to confusion as many patches
> don't have just one "original" author, e.g. when multiple developers
> are involved from the genesis of the patch.  Remove all usage of
> "original" and instead call out that Co-developed-by is simply a way to
> provide attribution in addition to the From tag, i.e. neither tag is
> intended to imply anything with regard to who did what.
> 
> Provide examples to (hopefully) eliminate any ambiguity.
> 
> Cc: Tobin C. Harding <me@tobin.cc>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: Jorge Ramirez-Ortiz <jorge.ramirez-ortiz@linaro.org>
> Cc: Jonathan Cameron <jic23@kernel.org>
> Cc: Joe Perches <joe@perches.com>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Niklas Cassel <niklas.cassel@linaro.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com>
> ---
> 
> v1: https://lkml.kernel.org/r/20190320151140.32432-1-sean.j.christopherson@intel.com
> v2: https://lkml.kernel.org/r/20190321184316.8525-1-sean.j.christopherson@intel.com
>     Rewrite the blurb to state standard sign-off procedure should be
>     followed as opposed to dictating the original author's SOB be last.
> v3: https://lkml.kernel.org/r/20190321200103.9333-1-sean.j.christopherson@intel.com
>     Update a similar blurb in Documentation/process/5.Posting.rst
> v4: Rework the blurbs to avoid use of the word "original" [Tobin]
> 
>  Documentation/process/5.Posting.rst          | 10 +++--
>  Documentation/process/submitting-patches.rst | 40 +++++++++++++++++---
>  2 files changed, 41 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index 4213e580f273..d2da09372563 100644
> --- a/Documentation/process/5.Posting.rst
> +++ b/Documentation/process/5.Posting.rst
> @@ -216,10 +216,12 @@ The tags in common use are:
>     which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
>     Code without a proper signoff cannot be merged into the mainline.
>  
> - - Co-developed-by: states that the patch was also created by another developer
> -   along with the original author.  This is useful at times when multiple
> -   people work on a single patch.  Note, this person also needs to have a
> -   Signed-off-by: line in the patch as well.
> + - Co-developed-by: states that the patch was co-created by several developers;
> +   it is a used to give attribution to co-authors (in addition to the author
> +   atrributed by the From: tag) when multiple people work on a single patch.

fwiw

s/atrributed/attributed/

> +   Every Co-developed-by: must be immediately followed by a Signed-off-by: of
> +   the associated co-author.  Details and examples can be found in
> +   :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
>  
>   - Acked-by: indicates an agreement by another developer (often a
>     maintainer of the relevant code) that the patch is appropriate for
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index be7d1829c3af..06db26b12495 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -545,10 +545,40 @@ person it names - but it should indicate that this person was copied on the
>  patch.  This tag documents that potentially interested parties
>  have been included in the discussion.
>  
> -A Co-developed-by: states that the patch was also created by another developer
> -along with the original author.  This is useful at times when multiple people
> -work on a single patch.  Note, this person also needs to have a Signed-off-by:
> -line in the patch as well.
> +Co-developed-by: states that the patch was co-created by multiple developers;
> +it is a used to give attribution to co-authors (in addition to the author
> +attributed by the From: tag) when several people work on a single patch.  Since
> +Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
> +followed by a Signed-off-by: of the associated co-author.  Standard sign-off
> +procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
> +chronological history of the patch insofar as possible, regardless of whether
> +the author is attributed via From: or Co-developed-by:.  Notably, the last
> +Signed-off-by: must always be that of the developer submitting the patch.
> +
> +Note, the From: tag is optional when the From: author is also the person (and
> +email) listed in the From: line of the email header.
> +
> +Example of a patch submitted by the From: author::
> +
> +	<changelog>
> +
> +	Co-developed-by: First Co-Author <first@coauthor.example.org>
> +	Signed-off-by: First Co-Author <first@coauthor.example.org>
> +	Co-developed-by: Second Co-Author <second@coauthor.example.org>
> +	Signed-off-by: Second Co-Author <second@coauthor.example.org>
> +	Signed-off-by: From Author <from@author.example.org>
> +
> +Example of a patch submitted by a Co-developed-by: author::
> +
> +	From: From Author <from@author.example.org>
> +
> +	<changelog>
> +
> +	Co-developed-by: Random Co-Author <random@coauthor.example.org>
> +	Signed-off-by: Random Co-Author <random@coauthor.example.org>
> +	Signed-off-by: From Author <from@author.example.org>
> +	Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
> +	Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
>  
>  
>  13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
> @@ -696,7 +726,7 @@ A couple of example Subjects::
>  The ``from`` line must be the very first line in the message body,
>  and has the form:
>  
> -        From: Original Author <author@example.com>
> +        From: Patch Author <author@example.com>
>  
>  The ``from`` line specifies who will be credited as the author of the
>  patch in the permanent changelog.  If the ``from`` line is missing,
> -- 
> 2.21.0
>