From nobody Tue Dec 16 16:38:42 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