Re: [PATCH v5 1/2] docs: Clarify the usage and sign-off requirements for Co-developed-by

From: Tobin C. Harding
Date: Fri Mar 22 2019 - 22:06:54 EST


On Fri, Mar 22, 2019 at 02:11:36PM -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>
> ---
> 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..855a70b80269 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
> + attributed 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@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
>

Crystal clear now, thanks.

Tobin