Skip to content

Commit 07f33e7

Browse files
committed
Expand discussion of LLM use in contributions
We have some more experience of external and internal use of AI/LLM tooling on Qiskit since the last time we updated this section of the contributing guide. This is a revised version of the guidance, which attempts to more clearly direct use of the tools, based on patterns of use we have observed over the last few months. The policy espoused here should not be substantially different from the policy before this commit, other than a relaxation of the largely unenforceable rules about only using tools that have code-filtering capabilities. However, this new form should be clearer about expectations on contributors, and give more guidance about when AI-tool use is not appropriate. I also included a couple of lines that clarify that maintainers are not obliged to accept PRs, even ones that the contributor feels follow the letter of the guidance.
1 parent 7c68010 commit 07f33e7

1 file changed

Lines changed: 89 additions & 14 deletions

File tree

CONTRIBUTING.md

Lines changed: 89 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -216,23 +216,32 @@ please ensure that:
216216
If your code fails the local style checks (specifically the black
217217
or Rust code formatting check) you can use `tox -eblack` and
218218
`cargo fmt` to automatically fix the code formatting.
219+
219220
2. The documentation has been updated accordingly. In particular, if a
220221
function or class has been modified during the PR, please update the
221222
*docstring* accordingly.
222223

223224
If your pull request is adding a new class, function, or module that is
224225
intended to be user facing ensure that you've also added those to a
225226
documentation `autosummary` index to include it in the api documentation.
227+
226228
3. If you are of the opinion that the modifications you made warrant additional tests,
227229
feel free to include them
230+
228231
4. Ensure that if your change has an end user facing impact (new feature,
229232
deprecation, removal etc) that you have added a reno release note for that
230233
change and that the PR is tagged for the changelog.
234+
231235
5. All contributors have signed the CLA.
236+
232237
6. The PR has a concise and explanatory title (e.g. `Fixes Issue1234` is a bad title!).
238+
233239
7. If the PR addresses an open issue the PR description includes the `fixes #issue-number`
234-
syntax to link the PR to that issue (**you must use the exact phrasing in order for GitHub
235-
to automatically close the issue when the PR merges**)
240+
syntax to link the PR to that issue (**you must use the exact phrasing in order for GitHub
241+
to automatically close the issue when the PR merges**)
242+
243+
8. You have disclosed any use of AI tooling, including large language models (LLMs).
244+
See [Use of AI tools](#use-of-ai-tools) for your responsibilities.
236245

237246
### Code Review
238247

@@ -253,23 +262,89 @@ sure to always be kind and respectful in your interactions with maintainers and
253262

254263
### Use of AI tools
255264

256-
> [!WARNING]
257-
> If you use any AI tool while preparing your code contribution, you **must** disclose the name of the tool and its version in the PR description.
265+
> [!NOTE]
266+
> By "AI tools", we mean generative langauge tools like large language models (LLMs).
267+
268+
*You are responsible for any code you submit to Qiskit, no matter how it was generated.*
269+
270+
We discourage the use of LLM code generation, but do not forbid it in high-quality pull requests.
271+
272+
Qiskit maintainers are not obliged to accept any pull request, even if it follows these guidelines.
273+
Pull requests that require excessive maintainer time may be closed, even with no proposed
274+
alternative.
275+
276+
#### Your responsibilities
277+
278+
Your responsibilities for your code are not changed by using generative AI tooling. Some of these
279+
(this is not an exhaustive list) are:
280+
281+
- You have reviewed and fully understand all code you submit, and explain the reasoning for it.
282+
Asking an LLM to explain the reasoning for you is not acceptable.
283+
284+
- Your use of the AI tool, or the use of the output in Qiskit, does not violate any third-party
285+
license obligations of source code used during the generation. This may mean including license
286+
notices or source attribution with the generated code.
287+
288+
- The AI tool's terms and conditions must allow its output to be used in open-source projects, and
289+
they are compatible with submitting code under the [Qiskit license](LICENSE.txt), and abiding by
290+
the [Qiskit CLA](https://qisk.it/cla) and these contribution guidelines.
291+
292+
By submitting code to Qiskit, you are asserting that your submission is your own original work of
293+
authorship, as required by the [Contributor License Agreement (CLA)](https://qisk.it/cla) that you
294+
signed (or will sign) on your first contribution to Qiskit.
295+
296+
All non-trivial generated code must be clearly marked with code comments that:
297+
298+
- include the name and version of the model and tool used;
299+
- indicate the start and end of the generated code.
300+
301+
For example, you might write:
302+
303+
```python
304+
class SomeTranspilerPass:
305+
# This `run` method was originally generated using Claude Opus 4.6, then tidied up by hand.
306+
def run(self, dag):
307+
# [ ... generated code ... ]
308+
```
309+
310+
It is never appropriate to allow an unsupervised agent to interact publicly with the Qiskit
311+
repository.
312+
313+
#### Appropriate use of AI tools
314+
315+
We understand that using AI tooling is fun, and feels very productive. However, AI tooling is just
316+
a tool, and is not always appropriate.
317+
318+
It is generally fine to use AI tooling privately in chat mode to ask about the existing code,
319+
prototype solutions, and debug issues. Private use, where no LLM output becomes submitted code or
320+
public communications, does not need disclosure. Be aware that writing code that is based on other
321+
code (such as re-implementing LLM-output code yourself) may still be subject to licensing
322+
restrictions from the source.
323+
324+
It is generally not ok to use AI tooling to produce code that you could not subsequently reproduce
325+
yourself later without tooling, including if the AI tooling only provided explanations. This would
326+
indicate that you do not sufficiently understand the code produced.
327+
328+
Some questions to ask yourself:
329+
330+
- *Have I reviewed and thought about the code in as much depth as I would have without the tool?*
258331

259-
When using AI tools for code generation, your submission must still be your own original work of authorship, as required by the [Contributor License Agreement (CLA)](https://qisk.it/cla). It is your responsibility to make sure that:
332+
The hardest part of producing high-quality software is not writing lines of code. It is far
333+
harder to review code for correctness and for whole-project architectural fit, and to make sure
334+
that code is solving problems in the right way.
260335

261-
- You review and fully understand the generated code, and you can explain the reasoning behind it during review.
262-
- The usage of the AI tool does not violate any third-party license obligations.
263-
- The AI tool's terms and conditions allow its output to be used in open source projects and are compatible with the [Qiskit license](LICENSE.txt), the [Qiskit CLA](https://qisk.it/cla), and [these Contributor Guidelines](CONTRIBUTING.md).
264-
- You only use AI tools that have features to:
265-
* filter out generated code substantially similar to training data, or
266-
* identify similar training code so you can comply with the original license obligations (notice, attribution, etc.) and only contribute if it's compatible with the [Qiskit license](LICENSE.txt).
267-
- You disclose the name and version of the AI tool in your PR description.
336+
- *Have I been respectful of the time the code review will take?*
268337

269-
Submissions that appear unreviewed or copied directly from an AI tool without proper understanding may be requested to be revised or declined.
338+
By submitting code to Qiskit, you are asking a maintainer to review it. It is very easy to
339+
quickly generate large quantities of code with an LLM, yet all code must be reviewed. Qiskit
340+
maintainers will close PRs that indicate the submitter is not respecting the time of the humans
341+
on the maintenance side.
270342

271-
Remember that spamming issues or pull requests with AI-generated comments is prohibited under the [Qiskit Code of Conduct](https://qisk.it/coc).
343+
- *What am I, the person, bringing to this process?*
272344

345+
Remember that Qiskit maintainers have access to AI tools too. If the majority of your involvement
346+
was to point an AI tool at an open issue and ask it to fix it, consider that we could have done
347+
that too and there was a reason we didn't.
273348

274349
## Contributor Licensing Agreement
275350

0 commit comments

Comments
 (0)