From 726ec3cc33a0fda5f90be54ffb1cd641608b579f Mon Sep 17 00:00:00 2001 From: mariatta Date: Wed, 8 Apr 2026 16:47:02 -0700 Subject: [PATCH 01/11] Update guidelines on using GenAI Co-authored-by: Gregory P. Smith Co-authored-by: Donghee Na Co-authored-by: devdanzin <74280297+devdanzin@users.noreply.github.com> --- getting-started/generative-ai.rst | 44 ++++++++++++++++++------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index e4aa3e7586..0aab067abb 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -4,10 +4,10 @@ Generative AI ============= -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. +Generative AI tools are evolving rapidly, and their work 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. Acceptable uses =============== @@ -21,20 +21,28 @@ 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 whether +AI was used or not. + +If a contributor repeatedly opens unproductive issues or PRs, they may be blocked. + +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 and are not acceptable. 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 + +Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR. + +We expect PR authors to be able to explain their proposed changes in their own words. + +Disclose the use of AI tools in the PR description, and be prepared to explain how the tool was used and what +changes it made. + +Whether you are using Generative AI 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 From e71105ba42573a6d54de532c256990a03f3ee47a Mon Sep 17 00:00:00 2001 From: Mariatta Date: Wed, 8 Apr 2026 17:05:18 -0700 Subject: [PATCH 02/11] Update getting-started/generative-ai.rst Co-authored-by: Jacob Coffee --- getting-started/generative-ai.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index 0aab067abb..c80d76f6b8 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -21,7 +21,7 @@ Some of the acceptable uses of generative AI include: Unacceptable uses ================= -Maintainers may close issues and PRs that are not useful or productive, regardless whether +Maintainers may close issues and PRs that are not useful or productive, regardless of whether AI was used or not. If a contributor repeatedly opens unproductive issues or PRs, they may be blocked. From f8ab6abc03f6074ae1e7d8791383a65f9daff195 Mon Sep 17 00:00:00 2001 From: mariatta Date: Wed, 8 Apr 2026 17:22:14 -0700 Subject: [PATCH 03/11] Update the title to clarify the purpose of this doc is to provide guidelines. Add the Guidelines to the contributing table. --- getting-started/generative-ai.rst | 8 ++++---- index.rst | 4 +++- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index c80d76f6b8..4f762b99ae 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -1,8 +1,8 @@ .. _generative-ai: -============= -Generative AI -============= +================================= +Guidelines in using Generative AI +================================= Generative AI tools are evolving rapidly, and their work can be helpful. As with using any tool, the resulting contribution is the responsibility of the contributor. We value good code, concise accurate documentation, @@ -36,7 +36,7 @@ Authors must review the work done by AI tooling in detail to ensure it actually We expect PR authors to be able to explain their proposed changes in their own words. -Disclose the use of AI tools in the PR description, and be prepared to explain how the tool was used and what +Disclosure of the use of AI tools in the PR description, and be prepared to explain how the tool was used and what changes it made. Whether you are using Generative AI or not, keep the following principles in mind for the quality diff --git a/index.rst b/index.rst index 18aca244e1..61aac7f527 100644 --- a/index.rst +++ b/index.rst @@ -40,6 +40,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` + * :ref:`generative-ai` - * :ref:`setup` * :ref:`help` @@ -49,7 +50,8 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` - - + * :ref:`generative-ai` +- * :ref:`tracker` * :ref:`triaging` * :ref:`helptriage` From a04cd52189e3bbdc3b0c04ff4db9d5f666d9b6aa Mon Sep 17 00:00:00 2001 From: mariatta Date: Wed, 8 Apr 2026 17:27:51 -0700 Subject: [PATCH 04/11] Fix the markup in rendering the table --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.rst b/index.rst index 61aac7f527..af8a612df4 100644 --- a/index.rst +++ b/index.rst @@ -51,7 +51,7 @@ Guide for contributing to Python: * :ref:`gitbootcamp` * :ref:`devcycle` * :ref:`generative-ai` -- + - * :ref:`tracker` * :ref:`triaging` * :ref:`helptriage` From ef31ff8eb42a7ea1159599b371834cb191961870 Mon Sep 17 00:00:00 2001 From: mariatta Date: Wed, 8 Apr 2026 17:31:32 -0700 Subject: [PATCH 05/11] Soften the wording about AI tool disclosure. --- getting-started/generative-ai.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index 4f762b99ae..412abd49be 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -36,8 +36,8 @@ Authors must review the work done by AI tooling in detail to ensure it actually We expect PR authors to be able to explain their proposed changes in their own words. -Disclosure of the use of AI tools in the PR description, and be prepared to explain how the tool was used and what -changes it made. +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 Generative AI or not, keep the following principles in mind for the quality of your contribution: From ff94cd6018506c49d4e61c06370908f8f8cf7b4a Mon Sep 17 00:00:00 2001 From: mariatta Date: Wed, 8 Apr 2026 17:33:54 -0700 Subject: [PATCH 06/11] Moved the considerations to be earlier in the page. --- getting-started/generative-ai.rst | 36 +++++++++++++++---------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index 412abd49be..0d7aa7a92b 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -9,6 +9,24 @@ contribution is the responsibility of the contributor. We value good code, conci 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. +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. + +We expect PR authors 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 Generative AI 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 + Acceptable uses =============== @@ -28,21 +46,3 @@ If a contributor repeatedly opens unproductive issues or PRs, they may be blocke 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 and are not acceptable. - -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. - -We expect PR authors 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 Generative AI 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 From c827f75f7bb4c7586bc99bfcd97f7e5bd0f4dc36 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Mon, 18 May 2026 17:53:18 -0700 Subject: [PATCH 07/11] Apply suggestions from code review Co-authored-by: Savannah Ostrowski Co-authored-by: Carol Willing --- getting-started/generative-ai.rst | 16 ++++++++-------- index.rst | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index 0d7aa7a92b..f4c45bef7d 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -1,25 +1,25 @@ -.. _generative-ai: +.. _ai-tools: ================================= -Guidelines in using Generative AI +Guidelines for using AI tools ================================= -Generative AI tools are evolving rapidly, and their work can be helpful. As with using any tool, the resulting +Generative AI tools can produce output quickly. 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 +and well scoped PRs without unneeded code churn. Discretion, good judgment, and critical thinking are the foundation of all good contributions, regardless of the tools used in their creation. 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. +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 to be able to explain their proposed changes in their own words. +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 Generative AI or not, keep the following principles in mind for the quality +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 @@ -40,7 +40,7 @@ Unacceptable uses ================= Maintainers may close issues and PRs that are not useful or productive, regardless of whether -AI was used or not. +AI tools were used or not. If a contributor repeatedly opens unproductive issues or PRs, they may be blocked. diff --git a/index.rst b/index.rst index af8a612df4..eb8134e904 100644 --- a/index.rst +++ b/index.rst @@ -40,7 +40,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` - * :ref:`generative-ai` + * :ref:`ai-tools` - * :ref:`setup` * :ref:`help` @@ -50,7 +50,7 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` - * :ref:`generative-ai` + * :ref:`ai-tools` - * :ref:`tracker` * :ref:`triaging` From 04063151c0c43b26208d7634c0c26998d2b1afaf Mon Sep 17 00:00:00 2001 From: mariatta Date: Tue, 19 May 2026 12:10:56 -0700 Subject: [PATCH 08/11] Update based on comments. --- getting-started/generative-ai.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index f4c45bef7d..18edc71d69 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -26,6 +26,9 @@ of your contribution: - 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 =============== @@ -44,5 +47,5 @@ AI tools were used or not. If a contributor repeatedly opens unproductive issues or PRs, they may be blocked. -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 and are not acceptable. +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. From 4092cf2be68684c3b3f9fa7f814110015028defa Mon Sep 17 00:00:00 2001 From: mariatta Date: Tue, 19 May 2026 12:11:20 -0700 Subject: [PATCH 09/11] remove extra header lines --- getting-started/generative-ai.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index 18edc71d69..b8224da7b7 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -1,8 +1,8 @@ .. _ai-tools: -================================= +============================= Guidelines for using AI tools -================================= +============================= Generative AI tools can produce output quickly. As with using any tool, the resulting contribution is the responsibility of the contributor. We value good code, concise accurate documentation, From 84f3cbd001d77ffcf4228ed6098eab7bef2b11ef Mon Sep 17 00:00:00 2001 From: mariatta Date: Tue, 19 May 2026 12:15:37 -0700 Subject: [PATCH 10/11] Add more explicit in the beginning that the person submitting issue or pr is responsible for its content. --- getting-started/generative-ai.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index b8224da7b7..ce18c164b6 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -4,10 +4,11 @@ Guidelines for using AI tools ============================= -Generative AI tools can produce output quickly. As with using any tool, the resulting -contribution is the responsibility of the contributor. We value good code, concise accurate documentation, -and well scoped PRs without 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 ========================== From 2aad5605297ee70e0f9f0efde3cfb5f801cfff13 Mon Sep 17 00:00:00 2001 From: mariatta Date: Tue, 19 May 2026 16:18:25 -0700 Subject: [PATCH 11/11] adjust wording about being disrespectful and about reviewing the output always. --- getting-started/generative-ai.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst index ce18c164b6..7c84e5bcbe 100644 --- a/getting-started/generative-ai.rst +++ b/getting-started/generative-ai.rst @@ -29,7 +29,7 @@ of your contribution: - 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. +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 =============== @@ -46,7 +46,9 @@ Unacceptable uses Maintainers may close issues and PRs that are not useful or productive, regardless of whether AI tools were used or not. -If a contributor repeatedly opens unproductive issues or PRs, they may be blocked. +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. 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.