Guidelines for using AI tools

The person submitting an issue or PR is responsible for its content, regardless of whether AI tools were used in its creation. Generative AI tools can produce output quickly, but discretion, good judgment, and critical thinking are the foundation of all good contributions. We value good code, concise accurate documentation, and well scoped PRs without unneeded code churn.

Considerations for success

Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR or filing it as an issue.

We expect PR authors and those filing issues to be able to explain their proposed changes in their own words. If you are new to contributing to Python or only started recently, also read the additional rules for new contributors.

Disclosure of the use of AI tools in the PR description is appreciated, while not required. Be prepared to explain how the tool was used and what changes it made.

Whether you are using AI tools or not, keep the following principles in mind for the quality of your contribution:

  • Consider whether the change is necessary

  • Make minimal, focused changes

  • Follow existing coding style and patterns

  • Write tests that exercise the change

  • Keep backwards compatibility with prior releases in mind. Existing tests may be ensuring specific API behaviors are maintained.

Pay close attention to AI generated recommendations for testing changes. Provide input about Python’s testing principles when guiding an AI model. Always review the output before opening a pull request or issue, including proposed PR or issue titles and descriptions.

Acceptable uses

Some of the acceptable uses of generative AI include:

  • Assistance with writing issues, PR descriptions and comments, especially in a non-native language

  • Gaining understanding of existing code

  • Supplementing contributor knowledge for code, tests, and documentation

AI-generated text is often verbose and hides the point. When an AI tool helps you write, remove filler, repetition and generic phrasing, and keep only what you have checked and agree with. When it translates text you wrote in another language, consider saying so and including your original text, unedited, in a <details> block, so that readers can refer to your own words:

<details>
<summary>Original text</summary>

Elen síla lúmenn' omentielvo.

</details>

Unacceptable uses

Maintainers may close issues and PRs that are not useful or productive, without explanation, regardless of whether AI tools were used or not.

If a contributor repeatedly opens unproductive issues or PRs, they may be blocked from contributing to the project because it is disruptive and disrespectful of the maintainers time.

Other unacceptable uses include:

  • Communicating only through an AI tool, for example by passing reviewers’ questions to it and posting its answers as your own. Apart from translating text you wrote, reviewers expect to discuss the change with you. If you do not know the answer to a question, say so.

  • Altering or bypassing existing tests, or removing desired functionality, in order to make a failing test pass. Such changes are not a real fix.

Additional rules for new contributors

People who want to start contributing to Python, or who have only recently started and are still learning the code base, are welcome, and we want their first contributions to reflect their own understanding.

As a new contributor, you may use AI tools to understand an issue or the code it involves, but the work itself must be yours: writing the change, its tests and its description is how you learn the code base. Reading a finished change is not the same as understanding it; as such, letting an AI tool do the work and only reviewing its output is not considered acceptable.

How these guidelines are applied

Using AI tools is not a reason on its own for an issue or PR to be labeled or closed. When a maintainer thinks an issue or PR does not follow these guidelines, they may apply one of the following labels. A bot then posts a comment that links to this page.

  • AI-needs-explanation: the issue or PR stays open. Reply in your own words: explain what the change does or what the issue is about, and describe how you checked that it is correct.

  • AI-guidelines-not-met: the issue or PR is closed. If you think we misunderstood your contribution, reply on the issue or PR. You are welcome to explain your approach or ask questions about these guidelines.