| 1 | .. _code-provenance: |
| 2 | |
| 3 | Code provenance |
| 4 | =============== |
| 5 | |
| 6 | Certifying patch submissions |
| 7 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 8 | |
| 9 | The QEMU community **mandates** all contributors to certify provenance of |
| 10 | patch submissions they make to the project. To put it another way, |
| 11 | contributors must indicate that they are legally permitted to contribute to |
| 12 | the project. |
| 13 | |
| 14 | Certification is achieved with a low overhead by adding a single line to the |
| 15 | bottom of every git commit:: |
| 16 | |
| 17 | Signed-off-by: YOUR NAME <YOUR@EMAIL> |
| 18 | |
| 19 | The addition of this line asserts that the author of the patch is contributing |
| 20 | in accordance with the clauses specified in the |
| 21 | `Developer's Certificate of Origin <https://developercertificate.org>`__: |
| 22 | |
| 23 | .. _dco: |
| 24 | |
| 25 | Developer's Certificate of Origin 1.1 |
| 26 | |
| 27 | By making a contribution to this project, I certify that: |
| 28 | |
| 29 | (a) The contribution was created in whole or in part by me and I |
| 30 | have the right to submit it under the open source license |
| 31 | indicated in the file; or |
| 32 | |
| 33 | (b) The contribution is based upon previous work that, to the best |
| 34 | of my knowledge, is covered under an appropriate open source |
| 35 | license and I have the right under that license to submit that |
| 36 | work with modifications, whether created in whole or in part |
| 37 | by me, under the same open source license (unless I am |
| 38 | permitted to submit under a different license), as indicated |
| 39 | in the file; or |
| 40 | |
| 41 | (c) The contribution was provided directly to me by some other |
| 42 | person who certified (a), (b) or (c) and I have not modified |
| 43 | it. |
| 44 | |
| 45 | (d) I understand and agree that this project and the contribution |
| 46 | are public and that a record of the contribution (including all |
| 47 | personal information I submit with it, including my sign-off) is |
| 48 | maintained indefinitely and may be redistributed consistent with |
| 49 | this project or the open source license(s) involved. |
| 50 | |
| 51 | The name used with "Signed-off-by" does not need to be your legal name, nor |
| 52 | birth name, nor appear on any government ID. It is the identity you choose to |
| 53 | be known by in the community, but should not be anonymous, nor misrepresent |
| 54 | whom you are. |
| 55 | |
| 56 | It is generally expected that the name and email addresses used in one of the |
| 57 | ``Signed-off-by`` lines, matches that of the git commit ``Author`` field. |
| 58 | It's okay if you subscribe or contribute to the list via more than one |
| 59 | address, but using multiple addresses in one commit just confuses |
| 60 | things. |
| 61 | |
| 62 | If the person sending the mail is not one of the patch authors, they are |
| 63 | nonetheless expected to add their own ``Signed-off-by`` to comply with the |
| 64 | DCO clause (c). |
| 65 | |
| 66 | Multiple authorship |
| 67 | ~~~~~~~~~~~~~~~~~~~ |
| 68 | |
| 69 | It is not uncommon for a patch to have contributions from multiple authors. In |
| 70 | this scenario, git commits will usually be expected to have a ``Signed-off-by`` |
| 71 | line for each contributor involved in creation of the patch. Some edge cases: |
| 72 | |
| 73 | * The non-primary author's contributions were so trivial that they can be |
| 74 | considered not subject to copyright. In this case the secondary authors |
| 75 | need not include a ``Signed-off-by``. |
| 76 | |
| 77 | This case most commonly applies where QEMU reviewers give short snippets |
| 78 | of code as suggested fixes to a patch. The reviewers don't need to have |
| 79 | their own ``Signed-off-by`` added unless their code suggestion was |
| 80 | unusually large, but it is common to add ``Suggested-by`` as a credit |
| 81 | for non-trivial code. |
| 82 | |
| 83 | * Both contributors work for the same employer and the employer requires |
| 84 | copyright assignment. |
| 85 | |
| 86 | It can be said that in this case a ``Signed-off-by`` is indicating that |
| 87 | the person has permission to contribute from their employer who is the |
| 88 | copyright holder. It is nonetheless still preferable to include a |
| 89 | ``Signed-off-by`` for each contributor, as in some countries employees are |
| 90 | not able to assign copyright to their employer, and it also covers any |
| 91 | time invested outside working hours. |
| 92 | |
| 93 | When multiple ``Signed-off-by`` tags are present, they should be strictly kept |
| 94 | in order of authorship, from oldest to newest. |
| 95 | |
| 96 | Other commit tags |
| 97 | ~~~~~~~~~~~~~~~~~ |
| 98 | |
| 99 | While the ``Signed-off-by`` tag is mandatory, there are a number of other tags |
| 100 | that are commonly used during QEMU development: |
| 101 | |
| 102 | * **Reviewed-by**: when a QEMU community member reviews a patch on the |
| 103 | mailing list, if they consider the patch acceptable, they should send an |
| 104 | email reply containing a ``Reviewed-by`` tag. Subsystem maintainers who |
| 105 | review a patch should add this even if they are also adding their |
| 106 | ``Signed-off-by`` to the same commit. |
| 107 | |
| 108 | * **Acked-by**: when a QEMU subsystem maintainer approves a patch that |
| 109 | touches their subsystem, but intends to allow a different maintainer to |
| 110 | queue it and send a pull request, they would send a mail containing a |
| 111 | ``Acked-by`` tag. Where a patch touches multiple subsystems, ``Acked-by`` |
| 112 | only implies review of the maintainers' own areas of responsibility. If a |
| 113 | maintainer wants to indicate they have done a full review they should use |
| 114 | a ``Reviewed-by`` tag. |
| 115 | |
| 116 | * **Tested-by**: when a QEMU community member has functionally tested the |
| 117 | behaviour of the patch in some manner, they should send an email reply |
| 118 | containing a ``Tested-by`` tag. |
| 119 | |
| 120 | * **Reported-by**: when a QEMU community member reports a problem via the |
| 121 | mailing list, or some other informal channel that is not the issue tracker, |
| 122 | it is good practice to credit them by including a ``Reported-by`` tag on |
| 123 | any patch fixing the issue. When the problem is reported via the GitLab |
| 124 | issue tracker, however, it is sufficient to just include a link to the |
| 125 | issue. |
| 126 | |
| 127 | * **Suggested-by**: when a reviewer or other 3rd party makes non-trivial |
| 128 | suggestions for how to change a patch, it is good practice to credit them |
| 129 | by including a ``Suggested-by`` tag. |
| 130 | |
| 131 | Subsystem maintainer requirements |
| 132 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 133 | |
| 134 | When a subsystem maintainer accepts a patch from a contributor, in addition to |
| 135 | the normal code review points, they are expected to validate the presence of |
| 136 | suitable ``Signed-off-by`` tags. |
| 137 | |
| 138 | At the time they queue the patch in their subsystem tree, the maintainer |
| 139 | **must** also then add their own ``Signed-off-by`` to indicate that they have |
| 140 | done the aforementioned validation. This is in addition to any of their own |
| 141 | ``Reviewed-by`` tags the subsystem maintainer may wish to include. |
| 142 | |
| 143 | When the maintainer modifies the patch after pulling into their tree, they |
| 144 | should record their contribution. This is typically done via a note in the |
| 145 | commit message, just prior to the maintainer's ``Signed-off-by``:: |
| 146 | |
| 147 | Signed-off-by: Cory Contributor <cory.contributor@example.com> |
| 148 | [Comment rephrased for clarity] |
| 149 | Signed-off-by: Mary Maintainer <mary.maintainer@mycorp.test> |
| 150 | |
| 151 | |
| 152 | Tools for adding ``Signed-off-by`` |
| 153 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 154 | |
| 155 | There are a variety of ways tools can support adding ``Signed-off-by`` tags |
| 156 | for patches, avoiding the need for contributors to manually type in this |
| 157 | repetitive text each time. |
| 158 | |
| 159 | git commands |
| 160 | ^^^^^^^^^^^^ |
| 161 | |
| 162 | When creating, or amending, a commit the ``-s`` flag to ``git commit`` will |
| 163 | append a suitable line matching the configured git author details. |
| 164 | |
| 165 | If preparing patches using the ``git format-patch`` tool, the ``-s`` flag can |
| 166 | be used to append a suitable line in the emails it creates, without modifying |
| 167 | the local commits. Alternatively to modify all the local commits on a branch:: |
| 168 | |
| 169 | git rebase master -x 'git commit --amend --no-edit -s' |
| 170 | |
| 171 | emacs |
| 172 | ^^^^^ |
| 173 | |
| 174 | In the file ``$HOME/.emacs.d/abbrev_defs`` add: |
| 175 | |
| 176 | .. code:: elisp |
| 177 | |
| 178 | (define-abbrev-table 'global-abbrev-table |
| 179 | '( |
| 180 | ("8rev" "Reviewed-by: YOUR NAME <your@email.addr>" nil 1) |
| 181 | ("8ack" "Acked-by: YOUR NAME <your@email.addr>" nil 1) |
| 182 | ("8test" "Tested-by: YOUR NAME <your@email.addr>" nil 1) |
| 183 | ("8sob" "Signed-off-by: YOUR NAME <your@email.addr>" nil 1) |
| 184 | )) |
| 185 | |
| 186 | with this change, if you type (for example) ``8rev`` followed by ``<space>`` |
| 187 | or ``<enter>`` it will expand to the whole phrase. |
| 188 | |
| 189 | vim |
| 190 | ^^^ |
| 191 | |
| 192 | In the file ``$HOME/.vimrc`` add:: |
| 193 | |
| 194 | iabbrev 8rev Reviewed-by: YOUR NAME <your@email.addr> |
| 195 | iabbrev 8ack Acked-by: YOUR NAME <your@email.addr> |
| 196 | iabbrev 8test Tested-by: YOUR NAME <your@email.addr> |
| 197 | iabbrev 8sob Signed-off-by: YOUR NAME <your@email.addr> |
| 198 | |
| 199 | with this change, if you type (for example) ``8rev`` followed by ``<space>`` |
| 200 | or ``<enter>`` it will expand to the whole phrase. |
| 201 | |
| 202 | Re-starting abandoned work |
| 203 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 204 | |
| 205 | For a variety of reasons there are some patches that get submitted to QEMU but |
| 206 | never merged. An unrelated contributor may decide (months or years later) to |
| 207 | continue working from the abandoned patch and re-submit it with extra changes. |
| 208 | |
| 209 | The general principles when picking up abandoned work are: |
| 210 | |
| 211 | * Continue to credit the original author for their work, by maintaining their |
| 212 | original ``Signed-off-by`` |
| 213 | * Indicate where the original patch was obtained from (mailing list, bug |
| 214 | tracker, author's git repo, etc) when sending it for review |
| 215 | * Acknowledge the extra work of the new contributor by including their |
| 216 | ``Signed-off-by`` in the patch in addition to the original author's |
| 217 | * Indicate who is responsible for what parts of the patch. This is typically |
| 218 | done via a note in the commit message, just prior to the new contributor's |
| 219 | ``Signed-off-by``:: |
| 220 | |
| 221 | Signed-off-by: Some Person <some.person@example.com> |
| 222 | [Rebased and added support for 'foo'] |
| 223 | Signed-off-by: New Person <new.person@mycorp.test> |
| 224 | |
| 225 | In complicated cases, or if otherwise unsure, ask for advice on the project |
| 226 | mailing list. |
| 227 | |
| 228 | It is also recommended to attempt to contact the original author to let them |
| 229 | know you are interested in taking over their work, in case they still intended |
| 230 | to return to the work, or had any suggestions about the best way to continue. |
| 231 | |
| 232 | Inclusion of generated files |
| 233 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 234 | |
| 235 | Files in patches contributed to QEMU are generally expected to be provided |
| 236 | only in the preferred format for making modifications. The implication of |
| 237 | this is that the output of code generators or compilers is usually not |
| 238 | appropriate to contribute to QEMU. |
| 239 | |
| 240 | For reasons of practicality there are some exceptions to this rule, where |
| 241 | generated code is permitted, provided it is also accompanied by the |
| 242 | corresponding preferred source format. This is done where it is impractical |
| 243 | to expect those building QEMU to run the code generation or compilation |
| 244 | process. A non-exhaustive list of examples is: |
| 245 | |
| 246 | * Images: where an bitmap image is created from a vector file it is common |
| 247 | to include the rendered bitmaps at desired resolution(s), since subtle |
| 248 | changes in the rasterization process / tools may affect quality. The |
| 249 | original vector file is expected to accompany any generated bitmaps. |
| 250 | |
| 251 | * Firmware: QEMU includes pre-compiled binary ROMs for a variety of guest |
| 252 | firmwares. When such binary ROMs are contributed, the corresponding source |
| 253 | must also be provided, either directly, or through a git submodule link. |
| 254 | |
| 255 | * Dockerfiles: the majority of the dockerfiles are automatically generated |
| 256 | from a canonical list of build dependencies maintained in tree, together |
| 257 | with the libvirt-ci git submodule link. The generated dockerfiles are |
| 258 | included in tree because it is desirable to be able to directly build |
| 259 | container images from a clean git checkout. |
| 260 | |
| 261 | * eBPF: QEMU includes some generated eBPF machine code, since the required |
| 262 | eBPF compilation tools are not broadly available on all targeted OS |
| 263 | distributions. The corresponding eBPF C code for the binary is also |
| 264 | provided. This is a time-limited exception until the eBPF toolchain is |
| 265 | sufficiently broadly available in distros. |
| 266 | |
| 267 | In all cases above, the existence of generated files must be acknowledged |
| 268 | and justified in the commit that introduces them. |
| 269 | |
| 270 | Tools which perform changes to existing code with deterministic algorithmic |
| 271 | manipulation, driven by user specified inputs, are not generally considered |
| 272 | to be "generators". |
| 273 | |
| 274 | For instance, using Coccinelle to convert code from one pattern to another |
| 275 | pattern, or fixing documentation typos with a spell checker, or transforming |
| 276 | code using sed / awk / etc, are not considered to be acts of code |
| 277 | generation. Where an automated manipulation is performed on code, however, |
| 278 | this should be declared in the commit message. |
| 279 | |
| 280 | At times contributors may use or create scripts/tools to generate an initial |
| 281 | boilerplate code template which is then filled in to produce the final patch. |
| 282 | The output of such a tool would still be considered the "preferred format", |
| 283 | since it is intended to be a foundation for further human authored changes. |
| 284 | Such tools are acceptable to use, provided there is clearly defined copyright |
| 285 | and licensing for their output. Note in particular the caveats applying to AI |
| 286 | content generators below. |
| 287 | |
| 288 | Use of AI-generated content |
| 289 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 290 | |
| 291 | TL;DR: |
| 292 | |
| 293 | **Current QEMU project policy is to DECLINE any contributions which are |
| 294 | believed to include or derive from AI generated content. This includes |
| 295 | ChatGPT, Claude, Copilot, Llama and similar tools.** |
| 296 | |
| 297 | **This policy does not apply to other uses of AI, such as researching APIs |
| 298 | or algorithms, static analysis, or debugging, provided their output is not |
| 299 | included in contributions.** |
| 300 | |
| 301 | The increasing prevalence of AI-assisted software development results in a |
| 302 | number of difficult legal questions and risks for software projects, including |
| 303 | QEMU. Of particular concern is content generated by `Large Language Models |
| 304 | <https://en.wikipedia.org/wiki/Large_language_model>`__ (LLMs). |
| 305 | |
| 306 | The QEMU community requires that contributors certify their patch submissions |
| 307 | are made in accordance with the rules of the `Developer's Certificate of |
| 308 | Origin (DCO) <dco>`. |
| 309 | |
| 310 | To satisfy the DCO, the patch contributor has to fully understand the |
| 311 | copyright and license status of content they are contributing to QEMU. With AI |
| 312 | content generators, the copyright and license status of the output is |
| 313 | ill-defined with no generally accepted, settled legal foundation. |
| 314 | |
| 315 | Where the training material is known, it is common for it to include large |
| 316 | volumes of material under restrictive licensing/copyright terms. Even where |
| 317 | the training material is all known to be under open source licenses, it is |
| 318 | likely to be under a variety of terms, not all of which will be compatible |
| 319 | with QEMU's licensing requirements. |
| 320 | |
| 321 | How contributors could comply with DCO terms (b) or (c) for the output of AI |
| 322 | content generators commonly available today is unclear. The QEMU project is |
| 323 | not willing or able to accept the legal risks of non-compliance. |
| 324 | |
| 325 | The QEMU project thus requires that contributors refrain from using AI content |
| 326 | generators on patches intended to be submitted to the project, and will |
| 327 | decline any contribution if use of AI is either known or suspected. |
| 328 | |
| 329 | Examples of tools impacted by this policy includes GitHub's CoPilot, OpenAI's |
| 330 | ChatGPT, Anthropic's Claude, and Meta's Code Llama, and code/content |
| 331 | generation agents which are built on top of such tools. |
| 332 | |
| 333 | This policy may evolve as AI tools mature and the legal situation is |
| 334 | clarified. |
| 335 | |
| 336 | Exceptions |
| 337 | ^^^^^^^^^^ |
| 338 | |
| 339 | The QEMU project welcomes discussion on any exceptions to this policy, |
| 340 | or more general revisions. This can be done by contacting the qemu-devel |
| 341 | mailing list with details of a proposed tool, model, usage scenario, etc. |
| 342 | that is beneficial to QEMU, while still mitigating issues around compliance |
| 343 | with the DCO. After discussion, any exception will be listed below. |
| 344 | |
| 345 | Exceptions do not remove the need for authors to comply with all other |
| 346 | requirements for contribution. In particular, the "Signed-off-by" |
| 347 | label in a patch submission is a statement that the author takes |
| 348 | responsibility for the entire contents of the patch, including any parts |
| 349 | that were generated or assisted by AI tools or other tools. |