Alex Bennée <alex.ben...@linaro.org> writes:
> Markus Armbruster <arm...@redhat.com> writes:
>
>> From: Daniel P. Berrangé <berra...@redhat.com>
>>
>> Currently we have a short paragraph saying that patches must include
>> a Signed-off-by line, and merely link to the kernel documentation.
>> The linked kernel docs have a lot of content beyond the part about
>> sign-off an thus are misleading/distracting to QEMU contributors.
>>
>> This introduces a dedicated 'code-provenance' page in QEMU talking
>> about why we require sign-off, explaining the other tags we commonly
>> use, and what to do in some edge cases.
>>
>> Signed-off-by: Daniel P. Berrangé <berra...@redhat.com>
>> Reviewed-by: Peter Maydell <peter.mayd...@linaro.org>
>> Signed-off-by: Markus Armbruster <arm...@redhat.com>
>> ---
>> docs/devel/code-provenance.rst | 218 ++++++++++++++++++++++++++++++
>> docs/devel/index-process.rst | 1 +
>> docs/devel/submitting-a-patch.rst | 18 +--
>> 3 files changed, 221 insertions(+), 16 deletions(-)
>> create mode 100644 docs/devel/code-provenance.rst
>>
>> diff --git a/docs/devel/code-provenance.rst b/docs/devel/code-provenance.rst
>> new file mode 100644
>> index 0000000000..4fc12061b5
>> --- /dev/null
>> +++ b/docs/devel/code-provenance.rst
>> @@ -0,0 +1,218 @@
>> +.. _code-provenance:
>> +
>> +Code provenance
>> +===============
>> +
>> +Certifying patch submissions
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The QEMU community **mandates** all contributors to certify provenance of
>> +patch submissions they make to the project. To put it another way,
>> +contributors must indicate that they are legally permitted to contribute to
>> +the project.
>> +
>> +Certification is achieved with a low overhead by adding a single line to the
>> +bottom of every git commit::
>
> s/git commit/commit/ throughout?
Yes.
>> +
>> + Signed-off-by: YOUR NAME <YOUR@EMAIL>
>> +
>> +using a known identity (sorry, no anonymous contributions.)
>> +
>
> maybe "(contributions cannot be anonymous)" is more direct?
If we're deviating from the kernel's text (which is *fine*), let's get
rid of the parenthesis:
using a known identity. Contributions cannot be anonymous.
or in active voice:
using a known identity. We cannot accept anonymous contributions.
I like this one the best.
>> +The addition of this line asserts that the author of the patch is
>> contributing
>> +in accordance with the clauses specified in the
>> +`Developer's Certificate of Origin <https://developercertificate.org>`__:
>> +
>> +.. _dco:
>> +
>> + Developer's Certificate of Origin 1.1
>> +
>> + By making a contribution to this project, I certify that:
>> +
>> + (a) The contribution was created in whole or in part by me and I
>> + have the right to submit it under the open source license
>> + indicated in the file; or
>> +
>> + (b) The contribution is based upon previous work that, to the best
>> + of my knowledge, is covered under an appropriate open source
>> + license and I have the right under that license to submit that
>> + work with modifications, whether created in whole or in part
>> + by me, under the same open source license (unless I am
>> + permitted to submit under a different license), as indicated
>> + in the file; or
>> +
>> + (c) The contribution was provided directly to me by some other
>> + person who certified (a), (b) or (c) and I have not modified
>> + it.
>> +
>> + (d) I understand and agree that this project and the contribution
>> + are public and that a record of the contribution (including all
>> + personal information I submit with it, including my sign-off) is
>> + maintained indefinitely and may be redistributed consistent with
>> + this project or the open source license(s) involved.
>> +
>> +It is generally expected that the name and email addresses used in one of
>> the
>> +``Signed-off-by`` lines, matches that of the git commit ``Author`` field.
>> +It's okay if you subscribe or contribute to the list via more than one
>> +address, but using multiple addresses in one commit just confuses
>> +things.
>> +
>> +If the person sending the mail is not one of the patch authors, they are
>> +nonetheless expected to add their own ``Signed-off-by`` to comply with the
>> +DCO clause (c).
>
> We should probably mention that sometimes the committer may update the
> patch after they have pulled it into the tree. In those cases we preface
> the S-o-B tag with a comment:
>
> Signed-off-by: Original Hacker <hacker@domain>
> [MH: tweaked the commit message for clarity]
> Signed-off-by: Maintainer Hacker <hac...@another.com>
Good idea. Should this go here or under "Subsystem maintainer
requirements"?
>> +
>> +Multiple authorship
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +It is not uncommon for a patch to have contributions from multiple authors.
>> In
>> +this scenario, git commits will usually be expected to have a
>> ``Signed-off-by``
>> +line for each contributor involved in creation of the patch. Some edge
>> cases:
>> +
>> + * The non-primary author's contributions were so trivial that they can be
>> + considered not subject to copyright. In this case the secondary authors
>> + need not include a ``Signed-off-by``.
>> +
>> + This case most commonly applies where QEMU reviewers give short snippets
>> + of code as suggested fixes to a patch. The reviewers don't need to have
>> + their own ``Signed-off-by`` added unless their code suggestion was
>> + unusually large, but it is common to add ``Suggested-by`` as a credit
>> + for non-trivial code.
>> +
>> + * Both contributors work for the same employer and the employer requires
>> + copyright assignment.
>> +
>> + It can be said that in this case a ``Signed-off-by`` is indicating that
>> + the person has permission to contribute from their employer who is the
>> + copyright holder. It is nonetheless still preferable to include a
>> + ``Signed-off-by`` for each contributor, as in some countries employees
>> are
>> + not able to assign copyright to their employer, and it also covers any
>> + time invested outside working hours.
>> +
>> +When multiple ``Signed-off-by`` tags are present, they should be strictly
>> kept
>> +in order of authorship, from oldest to newest.
>> +
>> +Other commit tags
>> +~~~~~~~~~~~~~~~~~
>> +
>> +While the ``Signed-off-by`` tag is mandatory, there are a number of other
>> tags
>> +that are commonly used during QEMU development:
>> +
>> + * **``Reviewed-by``**: when a QEMU community member reviews a patch on the
>> + mailing list, if they consider the patch acceptable, they should send an
>> + email reply containing a ``Reviewed-by`` tag. Subsystem maintainers who
>> + review a patch should add this even if they are also adding their
>> + ``Signed-off-by`` to the same commit.
>> +
>> + * **``Acked-by``**: when a QEMU subsystem maintainer approves a patch that
>> + touches their subsystem, but intends to allow a different maintainer to
>> + queue it and send a pull request, they would send a mail containing a
>> + ``Acked-by`` tag. Where a patch touches multiple subsystems, ``Acked-by``
>> + only implies review of the maintainers' own areas of responsibility. If a
>> + maintainer wants to indicate they have done a full review they should use
>> + a ``Reviewed-by`` tag.
>> +
>> + * **``Tested-by``**: when a QEMU community member has functionally tested
>> the
>> + behaviour of the patch in some manner, they should send an email reply
>> + containing a ``Tested-by`` tag.
>> +
>> + * **``Reported-by``**: when a QEMU community member reports a problem via
>> the
>> + mailing list, or some other informal channel that is not the issue
>> tracker,
>> + it is good practice to credit them by including a ``Reported-by`` tag on
>> + any patch fixing the issue. When the problem is reported via the GitLab
>> + issue tracker, however, it is sufficient to just include a link to the
>> + issue.
>
> We don't mention the Link: or Message-Id: tags.
Yes, but should it go into code-provenance.rst or
submitting-a-patch.rst?
You asked for guidance on use of "Message-Id:" in your review of v2. I
understand the practice, and can write guidance, but I wanted to get
this out before my vacation next week, so I left it for later, as
mentioned in the cover letter.
How do we use "Link:"? What about "Closes:"?
Here's what the kernel's submitting-patches.rst has to say:
Describe your changes
---------------------
[...]
If related discussions or any other background information behind the change
can be found on the web, add 'Link:' tags pointing to it. If the patch is a
result of some earlier mailing list discussions or something documented on
the
web, point to it.
When linking to mailing list archives, preferably use the lore.kernel.org
message archiver service. To create the link URL, use the contents of the
``Message-ID`` header of the message without the surrounding angle brackets.
For example::
Link: https://lore.kernel.org/30th.anniversary.rep...@klaava.helsinki.fi
Please check the link to make sure that it is actually working and points
to the relevant message.
However, try to make your explanation understandable without external
resources. In addition to giving a URL to a mailing list archive or bug,
summarize the relevant points of the discussion that led to the
patch as submitted.
In case your patch fixes a bug, use the 'Closes:' tag with a URL referencing
the report in the mailing list archives or a public bug tracker. For
example::
Closes: https://example.com/issues/1234
Some bug trackers have the ability to close issues automatically when a
commit with such a tag is applied. Some bots monitoring mailing lists can
also track such tags and take certain actions. Private bug trackers and
invalid URLs are forbidden.
and
Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
----------------------------------------------------------------------
The Reported-by tag gives credit to people who find bugs and report them
and it
hopefully inspires them to help us again in the future. The tag is intended
for
bugs; please do not use it to credit feature requests. The tag should be
followed by a Closes: tag pointing to the report, unless the report is not
available on the web. The Link: tag can be used instead of Closes: if the
patch
fixes a part of the issue(s) being reported. Note, the Reported-by tag is
one
of only three tags you might be able to use without explicit permission of
the
person named (see 'Tagging people requires permission' below for details).
>> +
>> + * **``Suggested-by``**: when a reviewer or other 3rd party makes
>> non-trivial
>> + suggestions for how to change a patch, it is good practice to credit them
>> + by including a ``Suggested-by`` tag.
>> +
>> +Subsystem maintainer requirements
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +When a subsystem maintainer accepts a patch from a contributor, in addition
>> to
>> +the normal code review points, they are expected to validate the presence of
>> +suitable ``Signed-off-by`` tags.
>> +
>> +At the time they queue the patch in their subsystem tree, the maintainer
>> +**must** also then add their own ``Signed-off-by`` to indicate that they
>> have
>> +done the aforementioned validation. This is in addition to any of their own
>> +``Reviewed-by`` tags the subsystem maintainer may wish to include.
>> +
>> +Tools for adding ``Signed-off-by``
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +There are a variety of ways tools can support adding ``Signed-off-by`` tags
>> +for patches, avoiding the need for contributors to manually type in this
>> +repetitive text each time.
>> +
>> +git commands
>> +^^^^^^^^^^^^
>> +
>> +When creating, or amending, a commit the ``-s`` flag to ``git commit`` will
>> +append a suitable line matching the configured git author details.
>> +
>> +If preparing patches using the ``git format-patch`` tool, the ``-s`` flag
>> can
>> +be used to append a suitable line in the emails it creates, without
>> modifying
>> +the local commits. Alternatively to modify all the local commits on a
>> branch::
>> +
>> + git rebase master -x 'git commit --amend --no-edit -s'
>> +
>
> Much as I love Emacs I wonder if this next section is worth it given the
> multiple ways you can solve this (I use yas-snippet expansions for
> example).
Showing one of them could still be useful for less experienced Emacs
users. We could mention it's just of many ways.
> If we do want to mention the editors we should probably also mention b4.
Can do if somebody contributes a suitable configuration snippet.
Thanks!
[...]
