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@xxxxxxxx>
> Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
> Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>
> Cc: Jorge Ramirez-Ortiz <jorge.ramirez-ortiz@xxxxxxxxxx>
> Cc: Jonathan Cameron <jic23@xxxxxxxxxx>
> Cc: Joe Perches <joe@xxxxxxxxxxx>
> Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> Cc: Niklas Cassel <niklas.cassel@xxxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Signed-off-by: Sean Christopherson <sean.j.christopherson@xxxxxxxxx>
> ---
> 
> v1: https://lkml.kernel.org/r/20190320151140.32432-1-sean.j.christopherson@xxxxxxxxx
> v2: https://lkml.kernel.org/r/20190321184316.8525-1-sean.j.christopherson@xxxxxxxxx
>     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@xxxxxxxxx
>     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@xxxxxxxxxxxxxxxxxxxx>
> +	Signed-off-by: First Co-Author <first@xxxxxxxxxxxxxxxxxxxx>
> +	Co-developed-by: Second Co-Author <second@xxxxxxxxxxxxxxxxxxxx>
> +	Signed-off-by: Second Co-Author <second@xxxxxxxxxxxxxxxxxxxx>
> +	Signed-off-by: From Author <from@xxxxxxxxxxxxxxxxxx>
> +
> +Example of a patch submitted by a Co-developed-by: author::
> +
> +	From: From Author <from@xxxxxxxxxxxxxxxxxx>
> +
> +	<changelog>
> +
> +	Co-developed-by: Random Co-Author <random@xxxxxxxxxxxxxxxxxxxx>
> +	Signed-off-by: Random Co-Author <random@xxxxxxxxxxxxxxxxxxxx>
> +	Signed-off-by: From Author <from@xxxxxxxxxxxxxxxxxx>
> +	Co-developed-by: Submitting Co-Author <sub@xxxxxxxxxxxxxxxxxxxx>
> +	Signed-off-by: Submitting Co-Author <sub@xxxxxxxxxxxxxxxxxxxx>
>  
>  
>  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@xxxxxxxxxxx>
> +        From: Patch Author <author@xxxxxxxxxxx>
>  
>  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
>