diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index e4aa3e758..ce18c164b 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -1,13 +1,35 @@ -.. _generative-ai: +.. _ai-tools: -============= -Generative AI -============= +============================= +Guidelines for using AI tools +============================= -Generative AI tools have evolved rapidly, and their suggested results can be helpful. As with using any tool, the resulting contribution is -the responsibility of the contributor. We value good code, concise accurate documentation, and avoiding unneeded code -churn. Discretion, good judgment, and critical thinking are the foundation of all good contributions, regardless of the -tools used in their creation. +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. + +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 from an AI model before opening a pull request or issue, including proposed PR or issue titles and descriptions. Acceptable uses =============== @@ -21,20 +43,10 @@ Some of the acceptable uses of generative AI include: Unacceptable uses ================= -Maintainers may close issues and PRs that are not useful or productive, including -those that are fully generated by AI. If a contributor repeatedly opens unproductive -issues or PRs, they may be blocked. +Maintainers may close issues and PRs that are not useful or productive, regardless of whether +AI tools were used or not. -Considerations for success -========================== -- While AI assisted tools such as autocompletion can enhance productivity, they sometimes rewrite entire code blocks instead of making small, focused edits. - This can make it more difficult to review changes and to fully understand both the original intent of the code and the rationale behind the new modifications. - Maintaining consistency with the original code helps preserve clarity, traceability, and meaningful reviews and also helps us avoid unnecessary code churn. -- Sometimes AI assisted tools make failing unit tests pass by altering or bypassing the tests rather than addressing the underlying problem in the code. - Such changes do not represent a real fix. Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR. -- Keep the following principles for the quality of your contributions in mind whether you use generative AI or not: - - - Consider whether the change is necessary - - Make minimal, focused changes - - Follow existing coding style and patterns - - Write tests that exercise the change +If a contributor repeatedly opens unproductive issues or PRs, they may be blocked. + +It is not acceptable to alter or bypass existing tests, or remove desired functionality, in order +to make a failing test pass. Such changes are not a real fix. diff --git a/index.rst b/index.rst index 4a478e7cc..fd67ac188 100644 --- a/index.rst +++ b/index.rst @@ -40,6 +40,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` + * :ref:`ai-tools` - * :ref:`setup` * :ref:`help` @@ -49,6 +50,7 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` + * :ref:`ai-tools` - * :ref:`tracker` * :ref:`triaging`