From nobody Tue Dec 16 08:52:31 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1750065999; cv=none; d=zohomail.com; s=zohoarc; b=hIQ2rBg6eSBNjGjVwfZyWmnl7YIxGqiXkMZ/MN2q3LFIyDPaLkN1y35rFE6p8OWSBF6edFgcDDOycSAoxj0i/bmOT3L1TVlam/BnnW4e1x0p7JPLhP9cy7SiFrHdbo5ONEF1QVpMRgaFu4RBjtkYcQGoUevmoTMOQ07aZTRUx8E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1750065999; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=BiIK4Ng2NUigzAsQEhP3LzUekXkRimZT+fiVxrWmEJk=; b=kqVsM82v0C6gc6/1//U9YmfP+mI3OsbBXfEz9V882Ahs5vYbmTuw7+R4F3ZRiCyANZRmue5KysX+PiYf5YfiNLW4zUT3qUajWvzHVRthnlzI26gYnUdPYCsQXp7hXXxtynxBLLnizthAomrTxltYv7XjD/CPG/v8qQSsaWoJ8cE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 175006599933538.65632158527649; Mon, 16 Jun 2025 02:26:39 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uR65M-0002lE-J0; Mon, 16 Jun 2025 05:25:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uR63N-0000Ou-8N for qemu-devel@nongnu.org; Mon, 16 Jun 2025 05:22:59 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uR63J-0005Ii-Vk for qemu-devel@nongnu.org; Mon, 16 Jun 2025 05:22:56 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-177--UT4I0qINQ63Wy8q6F-XHg-1; Mon, 16 Jun 2025 05:22:48 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8A4511808984; Mon, 16 Jun 2025 09:22:46 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.11]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 995D030044D8; Mon, 16 Jun 2025 09:22:45 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CA80321E6924; Mon, 16 Jun 2025 11:22:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1750065771; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=BiIK4Ng2NUigzAsQEhP3LzUekXkRimZT+fiVxrWmEJk=; b=QUSuN0oMX9jfkZp0GiZ5WJjvgcuLoSFRfUO3suqEBRbww3lYrUnixraygJjoUXuGfDIWrS nGnUDJoa0kaM+5b8n/RGxdX20/esQDDdc8s93SnnTD2AAds6tJfYdOeKqBI1CON0eG6ENG W3Dje2rjzfIFYDt6DGVgOmRvRf07zL8= X-MC-Unique: -UT4I0qINQ63Wy8q6F-XHg-1 X-Mimecast-MFC-AGG-ID: -UT4I0qINQ63Wy8q6F-XHg_1750065766 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Daniel=20P=20=2E=20Berrang=C3=A9?= , Thomas Huth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , "Michael S . Tsirkin" , Gerd Hoffmann , Mark Cave-Ayland , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Kevin Wolf , Stefan Hajnoczi , Alexander Graf , Paolo Bonzini , Richard Henderson , Peter Maydell Subject: [PATCH v5 1/3] docs: introduce dedicated page about code provenance / sign-off Date: Mon, 16 Jun 2025 11:22:39 +0200 Message-ID: <20250616092241.212898-2-armbru@redhat.com> In-Reply-To: <20250616092241.212898-1-armbru@redhat.com> References: <20250616092241.212898-1-armbru@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_FILL_THIS_FORM_SHORT=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1750066001485116600 From: Daniel P. Berrang=C3=A9 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=C3=A9 Reviewed-by: Peter Maydell Reviewed-by: Stefan Hajnoczi Reviewed-by: Alex Benn=C3=A9e Signed-off-by: Markus Armbruster --- docs/devel/code-provenance.rst | 230 ++++++++++++++++++++++++++++++ docs/devel/index-process.rst | 1 + docs/devel/submitting-a-patch.rst | 23 +-- 3 files changed, 233 insertions(+), 21 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..95b2dd34e2 --- /dev/null +++ b/docs/devel/code-provenance.rst @@ -0,0 +1,230 @@ +.. _code-provenance: + +Code provenance +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 t= he +bottom of every git commit:: + + Signed-off-by: YOUR NAME + +The addition of this line asserts that the author of the patch is contribu= ting +in accordance with the clauses specified in the +`Developer's Certificate of Origin `__: + +.. _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. + +The name used with "Signed-off-by" does not need to be your legal name, nor +birth name, nor appear on any government ID. It is the identity you choose= to +be known by in the community, but should not be anonymous, nor misrepresent +whom you are. + +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). + +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 cas= es: + + * 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 snippe= ts + 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 u= se + 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 trac= ker, + 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. + + * **``Suggested-by``**: when a reviewer or other 3rd party makes non-triv= ial + suggestions for how to change a patch, it is good practice to credit th= em + by including a ``Suggested-by`` tag. + +Subsystem maintainer requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a subsystem maintainer accepts a patch from a contributor, in additio= n 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 h= ave +done the aforementioned validation. This is in addition to any of their own +``Reviewed-by`` tags the subsystem maintainer may wish to include. + +When the maintainer modifies the patch after pulling into their tree, they +should record their contribution. This is typically done via a note in the +commit message, just prior to the maintainer's ``Signed-off-by``:: + + Signed-off-by: Cory Contributor + [Comment rephrased for clarity] + Signed-off-by: Mary Maintainer + + +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 modify= ing +the local commits. Alternatively to modify all the local commits on a bran= ch:: + + git rebase master -x 'git commit --amend --no-edit -s' + +emacs +^^^^^ + +In the file ``$HOME/.emacs.d/abbrev_defs`` add: + +.. code:: elisp + + (define-abbrev-table 'global-abbrev-table + '( + ("8rev" "Reviewed-by: YOUR NAME " nil 1) + ("8ack" "Acked-by: YOUR NAME " nil 1) + ("8test" "Tested-by: YOUR NAME " nil 1) + ("8sob" "Signed-off-by: YOUR NAME " nil 1) + )) + +with this change, if you type (for example) ``8rev`` followed by ``= `` +or ```` it will expand to the whole phrase. + +vim +^^^ + +In the file ``$HOME/.vimrc`` add:: + + iabbrev 8rev Reviewed-by: YOUR NAME + iabbrev 8ack Acked-by: YOUR NAME + iabbrev 8test Tested-by: YOUR NAME + iabbrev 8sob Signed-off-by: YOUR NAME + +with this change, if you type (for example) ``8rev`` followed by ``= `` +or ```` it will expand to the whole phrase. + +Re-starting abandoned work +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For a variety of reasons there are some patches that get submitted to QEMU= but +never merged. An unrelated contributor may decide (months or years later) = to +continue working from the abandoned patch and re-submit it with extra chan= ges. + +The general principles when picking up abandoned work are: + + * Continue to credit the original author for their work, by maintaining t= heir + original ``Signed-off-by`` + * Indicate where the original patch was obtained from (mailing list, bug + tracker, author's git repo, etc) when sending it for review + * Acknowledge the extra work of the new contributor by including their + ``Signed-off-by`` in the patch in addition to the orignal author's + * Indicate who is responsible for what parts of the patch. This is typica= lly + done via a note in the commit message, just prior to the new contributo= r's + ``Signed-off-by``:: + + Signed-off-by: Some Person + [Rebased and added support for 'foo'] + Signed-off-by: New Person + +In complicated cases, or if otherwise unsure, ask for advice on the project +mailing list. + +It is also recommended to attempt to contact the original author to let th= em +know you are interested in taking over their work, in case they still inte= nded +to return to the work, or had any suggestions about the best way to contin= ue. diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst index cb7c6640fd..5807752d70 100644 --- a/docs/devel/index-process.rst +++ b/docs/devel/index-process.rst @@ -13,6 +13,7 @@ Notes about how to interact with the community and how an= d where to submit patch maintainers style submitting-a-patch + code-provenance trivial-patches stable-process submitting-a-pull-request diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-pa= tch.rst index 65c64078cb..f7917b899f 100644 --- a/docs/devel/submitting-a-patch.rst +++ b/docs/devel/submitting-a-patch.rst @@ -344,28 +344,9 @@ Patch emails must include a ``Signed-off-by:`` line =20 Your patches **must** include a Signed-off-by: line. This is a hard requirement because it's how you say "I'm legally okay to contribute -this and happy for it to go into QEMU". The process is modelled after -the `Linux kernel -`__ -policy. +this and happy for it to go into QEMU". For full guidance, read the +:ref:`code-provenance` documentation. =20 -If you wrote the patch, make sure your "From:" and "Signed-off-by:" -lines use the same spelling. 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 someone else wrote the patch, git will -include a "From:" line in the body of the email (different from your -envelope From:) that will give credit to the correct author; but again, -that author's Signed-off-by: line is mandatory, with the same spelling. - -The name used with "Signed-off-by" does not need to be your legal name, -nor birth name, nor appear on any government ID. It is the identity you -choose to be known by in the community, but should not be anonymous, -nor misrepresent whom you are. - -There are various tooling options for automatically adding these tags -include using ``git commit -s`` or ``git format-patch -s``. For more -information see `SubmittingPatches 1.12 -`__. =20 .. _include_a_meaningful_cover_letter: =20 --=20 2.49.0 From nobody Tue Dec 16 08:52:31 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1750066023; cv=none; d=zohomail.com; s=zohoarc; b=UTLDF9s1GrMvz0NnlNeVXTd4RHdiGOlS477gmlA8KectydFOEpEvetXjkFkMERU3RD1E+uVEo5KCwspkL9JWBVQ+27btVMf5JLtIE+wmKPjl/FKRZRRQtBlQSig7LkhD5LMysbfJg/bit5yH2+4qyCuJhJoMoFfvQOUFrRCKz+c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1750066023; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=K55A2B61zQGD2o2fi+ByxssHvKopzLoWx1vnWo+3qNg=; b=a4+JLrOOUKhKDjWnj6C8mB4qy1QmCtRhS7qPxuYtZeEcS+qDCbS3DL7Vr8k87gn7sVFjckTIQGZSNjd3ONAK+1gKgA3d1ZS+PhHp37or1uWERQVZjKrxr0Aqh0slr3NUkw28cE+c09qonkD9USQ6tbewINApuvF6l1v9rM+KRT8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1750066023458421.4200749107665; Mon, 16 Jun 2025 02:27:03 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uR66X-0003ke-HG; Mon, 16 Jun 2025 05:26:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uR63O-0000Pv-WB for qemu-devel@nongnu.org; Mon, 16 Jun 2025 05:23:00 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uR63J-0005Hp-FH for qemu-devel@nongnu.org; Mon, 16 Jun 2025 05:22:58 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-372-y4VkaU5vN-WE_kwPWrnuOA-1; Mon, 16 Jun 2025 05:22:48 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 485FD180047F; Mon, 16 Jun 2025 09:22:46 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.11]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7FD4230044D6; Mon, 16 Jun 2025 09:22:45 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CF3B021E6925; Mon, 16 Jun 2025 11:22:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1750065769; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=K55A2B61zQGD2o2fi+ByxssHvKopzLoWx1vnWo+3qNg=; b=aXCqzx/EuQQe1LX7FdPM/lzfhUBy7sB7dFXQD7SG84gLKCXneGLGLzAOXI0WITM2ZGXh4Z Oktqx1lPXW9qJf9tW7DYX6jtt5OU39e/mEhLbw1dMdLgON8PMXsH66drQ5fO3aiIQsXgkY MUd5/7vrpD1twtEqrFZohXefvRvRL5M= X-MC-Unique: y4VkaU5vN-WE_kwPWrnuOA-1 X-Mimecast-MFC-AGG-ID: y4VkaU5vN-WE_kwPWrnuOA_1750065766 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Daniel=20P=20=2E=20Berrang=C3=A9?= , Thomas Huth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , "Michael S . Tsirkin" , Gerd Hoffmann , Mark Cave-Ayland , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Kevin Wolf , Stefan Hajnoczi , Alexander Graf , Paolo Bonzini , Richard Henderson , Peter Maydell Subject: [PATCH v5 2/3] docs: define policy limiting the inclusion of generated files Date: Mon, 16 Jun 2025 11:22:40 +0200 Message-ID: <20250616092241.212898-3-armbru@redhat.com> In-Reply-To: <20250616092241.212898-1-armbru@redhat.com> References: <20250616092241.212898-1-armbru@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_PASS=-0.001, T_SPF_HELO_TEMPERROR=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1750066025243116600 From: Daniel P. Berrang=C3=A9 Files contributed to QEMU are generally expected to be provided in the preferred format for manipulation. IOW, we generally don't expect to have generated / compiled code included in the tree, rather, we expect to run the code generator / compiler as part of the build process. There are some obvious exceptions to this seen in our existing tree, the biggest one being the inclusion of many binary firmware ROMs. A more niche example is the inclusion of a generated eBPF program. Or the CI dockerfiles which are mostly auto-generated. In these cases, however, the preferred format source code is still required to be included, alongside the generated output. Tools which perform user defined algorithmic transformations on code are not considered to be "code generators". ie, we permit use of coccinelle, spell checkers, and sed/awk/etc to manipulate code. Such use of automated manipulation should still be declared in the commit message. One off generators which create a boilerplate file which the author then fills in, are acceptable if their output has clear copyright and license status. This could be where a contributor writes a throwaway python script to automate creation of some mundane piece of code for example. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Alex Benn=C3=A9e Reviewed-by: Stefan Hajnoczi Signed-off-by: Markus Armbruster --- docs/devel/code-provenance.rst | 55 ++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/devel/code-provenance.rst b/docs/devel/code-provenance.rst index 95b2dd34e2..c25afed98d 100644 --- a/docs/devel/code-provenance.rst +++ b/docs/devel/code-provenance.rst @@ -228,3 +228,58 @@ mailing list. It is also recommended to attempt to contact the original author to let th= em know you are interested in taking over their work, in case they still inte= nded to return to the work, or had any suggestions about the best way to contin= ue. + +Inclusion of generated files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Files in patches contributed to QEMU are generally expected to be provided +only in the preferred format for making modifications. The implication of +this is that the output of code generators or compilers is usually not +appropriate to contribute to QEMU. + +For reasons of practicality there are some exceptions to this rule, where +generated code is permitted, provided it is also accompanied by the +corresponding preferred source format. This is done where it is impractical +to expect those building QEMU to run the code generation or compilation +process. A non-exhaustive list of examples is: + + * Images: where an bitmap image is created from a vector file it is common + to include the rendered bitmaps at desired resolution(s), since subtle + changes in the rasterization process / tools may affect quality. The + original vector file is expected to accompany any generated bitmaps. + + * Firmware: QEMU includes pre-compiled binary ROMs for a variety of guest + firmwares. When such binary ROMs are contributed, the corresponding sou= rce + must also be provided, either directly, or through a git submodule link. + + * Dockerfiles: the majority of the dockerfiles are automatically generated + from a canonical list of build dependencies maintained in tree, together + with the libvirt-ci git submodule link. The generated dockerfiles are + included in tree because it is desirable to be able to directly build + container images from a clean git checkout. + + * eBPF: QEMU includes some generated eBPF machine code, since the required + eBPF compilation tools are not broadly available on all targetted OS + distributions. The corresponding eBPF C code for the binary is also + provided. This is a time-limited exception until the eBPF toolchain is + sufficiently broadly available in distros. + +In all cases above, the existence of generated files must be acknowledged +and justified in the commit that introduces them. + +Tools which perform changes to existing code with deterministic algorithmic +manipulation, driven by user specified inputs, are not generally considered +to be "generators". + +For instance, using Coccinelle to convert code from one pattern to another +pattern, or fixing documentation typos with a spell checker, or transformi= ng +code using sed / awk / etc, are not considered to be acts of code +generation. Where an automated manipulation is performed on code, however, +this should be declared in the commit message. + +At times contributors may use or create scripts/tools to generate an initi= al +boilerplate code template which is then filled in to produce the final pat= ch. +The output of such a tool would still be considered the "preferred format", +since it is intended to be a foundation for further human authored changes. +Such tools are acceptable to use, provided there is clearly defined copyri= ght +and licensing for their output. --=20 2.49.0 From nobody Tue Dec 16 08:52:31 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1750065869; cv=none; d=zohomail.com; s=zohoarc; b=UFVUQ7n/pDCmE21gErU6Eye6IneOZ9ov/Gx912j8fPUdDSzY6yxd41WXwPNWS6V9EJbP9J/YdSpzRvuzcMD9vwCxGGY3OWsQw9cmAK+UKT0pla7/zOpXg8VsN1RdCVIcv/uNMJnbDDTrV/91ycuwYpf9IlOnaV4/ImFOHi6m5Ds= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1750065869; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=/57mASegoW8S7VeTMnJN+Cb99ND64Q2D44UkawBVIvY=; b=Ork2uRiK77QFJmbRmERxCNmy4Wd8/2LDxxUTxxVtVe+nPAzGso9Zjzjsh6wdHYkm4EAvFP6zRtudypXro0OfHQpo4fsrJ0G6irMswd1CsAGgDeI9APJfjFaqQrAJBXZ+ls+c4EUURF4MMjHS3J6iD4ZLrl9SXfBaBH8uGIACpm8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1750065869638610.9743532505925; Mon, 16 Jun 2025 02:24:29 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uR64B-0001W8-Sl; Mon, 16 Jun 2025 05:23:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uR63N-0000P1-Am for qemu-devel@nongnu.org; Mon, 16 Jun 2025 05:23:00 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uR63J-0005Je-LO for qemu-devel@nongnu.org; Mon, 16 Jun 2025 05:22:57 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-434-nyvLT8HWNpupm0VGxNkk_Q-1; Mon, 16 Jun 2025 05:22:49 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2B05818011CD; Mon, 16 Jun 2025 09:22:47 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.11]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7686C195608D; Mon, 16 Jun 2025 09:22:46 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D3BA921E6935; Mon, 16 Jun 2025 11:22:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1750065772; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=/57mASegoW8S7VeTMnJN+Cb99ND64Q2D44UkawBVIvY=; b=DhR1HIXaFPxcXHW9YdYgVi/dpfyRzYbeGyw8ryUhJNdAvJsndhEiqNPyBmBUEf8Hc4fP+F 0hNysyCXLlb+hnHcnkZJS5v+n0pMXTXU2wB9z/1hlyqyAad/X984jCz4xUUYDcN99qxMsC s8dcRutqGNOMSJwgtbkOLxTAQ270Lbs= X-MC-Unique: nyvLT8HWNpupm0VGxNkk_Q-1 X-Mimecast-MFC-AGG-ID: nyvLT8HWNpupm0VGxNkk_Q_1750065767 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Daniel=20P=20=2E=20Berrang=C3=A9?= , Thomas Huth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , "Michael S . Tsirkin" , Gerd Hoffmann , Mark Cave-Ayland , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Kevin Wolf , Stefan Hajnoczi , Alexander Graf , Paolo Bonzini , Richard Henderson , Peter Maydell Subject: [PATCH v5 3/3] docs: define policy forbidding use of AI code generators Date: Mon, 16 Jun 2025 11:22:41 +0200 Message-ID: <20250616092241.212898-4-armbru@redhat.com> In-Reply-To: <20250616092241.212898-1-armbru@redhat.com> References: <20250616092241.212898-1-armbru@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1750065873666116600 From: Daniel P. Berrang=C3=A9 There has been an explosion of interest in so called AI code generators. Thus far though, this is has not been matched by a broadly accepted legal interpretation of the licensing implications for code generator outputs. While the vendors may claim there is no problem and a free choice of license is possible, they have an inherent conflict of interest in promoting this interpretation. More broadly there is, as yet, no broad consensus on the licensing implications of code generators trained on inputs under a wide variety of licenses The DCO requires contributors to assert they have the right to contribute under the designated project license. Given the lack of consensus on the licensing of AI code generator output, it is not considered credible to assert compliance with the DCO clause (b) or (c) where a patch includes such generated code. This patch thus defines a policy that the QEMU project will currently not accept contributions where use of AI code generators is either known, or suspected. These are early days of AI-assisted software development. The legal questions will be resolved eventually. The tools will mature, and we can expect some to become safely usable in free software projects. The policy we set now must be for today, and be open to revision. It's best to start strict and safe, then relax. Meanwhile requests for exceptions can also be considered on a case by case basis. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Kevin Wolf Reviewed-by: Stefan Hajnoczi Reviewed-by: Alex Benn=C3=A9e Signed-off-by: Markus Armbruster --- docs/devel/code-provenance.rst | 55 +++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/docs/devel/code-provenance.rst b/docs/devel/code-provenance.rst index c25afed98d..b5aae2e253 100644 --- a/docs/devel/code-provenance.rst +++ b/docs/devel/code-provenance.rst @@ -282,4 +282,57 @@ boilerplate code template which is then filled in to p= roduce the final patch. The output of such a tool would still be considered the "preferred format", since it is intended to be a foundation for further human authored changes. Such tools are acceptable to use, provided there is clearly defined copyri= ght -and licensing for their output. +and licensing for their output. Note in particular the caveats applying to= AI +content generators below. + +Use of AI content generators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TL;DR: + + **Current QEMU project policy is to DECLINE any contributions which are + believed to include or derive from AI generated content. This includes + ChatGPT, Claude, Copilot, Llama and similar tools.** + +The increasing prevalence of AI-assisted software development results in a +number of difficult legal questions and risks for software projects, inclu= ding +QEMU. Of particular concern is content generated by `Large Language Models +`__ (LLMs). + +The QEMU community requires that contributors certify their patch submissi= ons +are made in accordance with the rules of the `Developer's Certificate of +Origin (DCO) `. + +To satisfy the DCO, the patch contributor has to fully understand the +copyright and license status of content they are contributing to QEMU. Wit= h AI +content generators, the copyright and license status of the output is +ill-defined with no generally accepted, settled legal foundation. + +Where the training material is known, it is common for it to include large +volumes of material under restrictive licensing/copyright terms. Even where +the training material is all known to be under open source licenses, it is +likely to be under a variety of terms, not all of which will be compatible +with QEMU's licensing requirements. + +How contributors could comply with DCO terms (b) or (c) for the output of = AI +content generators commonly available today is unclear. The QEMU project = is +not willing or able to accept the legal risks of non-compliance. + +The QEMU project thus requires that contributors refrain from using AI con= tent +generators on patches intended to be submitted to the project, and will +decline any contribution if use of AI is either known or suspected. + +This policy does not apply to other uses of AI, such as researching APIs or +algorithms, static analysis, or debugging, provided their output is not to= be +included in contributions. + +Examples of tools impacted by this policy includes GitHub's CoPilot, OpenA= I's +ChatGPT, Anthropic's Claude, and Meta's Code Llama, and code/content +generation agents which are built on top of such tools. + +This policy may evolve as AI tools mature and the legal situation is +clarifed. In the meanwhile, requests for exceptions to this policy will be +evaluated by the QEMU project on a case by case basis. To be granted an +exception, a contributor will need to demonstrate clarity of the license a= nd +copyright status for the tool's output in relation to its training model a= nd +code, to the satisfaction of the project maintainers. --=20 2.49.0