From 5b714661da7621865608449726fc845c890d79d7 Mon Sep 17 00:00:00 2001 From: Tobias Bieniek Date: Thu, 21 May 2026 11:11:35 +0200 Subject: [PATCH 1/4] docs: Add `AI-TOOLS.md` policy from python/devguide This imports the AI tools guidelines from the CPython devguide (python/devguide#1778) verbatim, as a starting point for our own policy. The text is licensed under CC0-1.0. Source: https://github.com/python/devguide/blob/main/getting-started/ai-tools.rst --- docs/AI-TOOLS.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/AI-TOOLS.md diff --git a/docs/AI-TOOLS.md b/docs/AI-TOOLS.md new file mode 100644 index 00000000000..00927971f86 --- /dev/null +++ b/docs/AI-TOOLS.md @@ -0,0 +1,56 @@ +# 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. + +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 comments, especially in a non-native language +- Gaining understanding of existing code +- Supplementing contributor knowledge for code, tests, and documentation + +## 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 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. From 45901963ad99da049692eedd78b8673539e4c8cb Mon Sep 17 00:00:00 2001 From: Tobias Bieniek Date: Thu, 21 May 2026 11:12:30 +0200 Subject: [PATCH 2/4] docs/AI-TOOLS: Drop Python-specific testing principles sentence crates.io has no published "testing principles" document equivalent to the one this sentence references, so the guidance does not translate. --- docs/AI-TOOLS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/AI-TOOLS.md b/docs/AI-TOOLS.md index 00927971f86..a354ee9b1c6 100644 --- a/docs/AI-TOOLS.md +++ b/docs/AI-TOOLS.md @@ -30,7 +30,6 @@ mind for the quality of your contribution: 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. From ec1c6b264974ca1c1edc23bb9ccdc67e40ac5aac Mon Sep 17 00:00:00 2001 From: Tobias Bieniek Date: Thu, 21 May 2026 11:32:06 +0200 Subject: [PATCH 3/4] AGENTS: Link to `AI-TOOLS.md` from reference material list --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index b020770a659..2b2fac3de88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -220,5 +220,6 @@ Before submitting: - `/docs/ARCHITECTURE.md` - System architecture and design decisions - `/docs/API-DESIGN.md` - JSON API conventions for new endpoints - `/docs/PR-REVIEW.md` - Guidelines for reviewing pull requests +- `/docs/AI-TOOLS.md` - Guidelines for using AI tools when contributing - `/script/import-database-dump.sh` - Import production database dump for testing - `/.github/workflows/ci.yml` - CI pipeline definition and tool versions From 7ecdf658024288ae361e70bc7acbc779d2b9850b Mon Sep 17 00:00:00 2001 From: Tobias Bieniek Date: Thu, 21 May 2026 11:33:44 +0200 Subject: [PATCH 4/4] docs/CONTRIBUTING: Add `Using AI tools` section --- docs/CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 66dc1fbc38c..8b2ab532da6 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,6 +1,7 @@ # Contributing to crates.io - [Attending the weekly team meetings](#attending-the-weekly-team-meetings) +- [Using AI tools](#using-ai-tools) - [Finding an issue to work on](#finding-an-issue-to-work-on) - [Submitting a Pull Request](#submitting-a-pull-request) - [Reviewing Pull Requests](#reviewing-pull-requests) @@ -17,6 +18,11 @@ everyone who wants to contribute to crates.io to participate. [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/318791-t-crates-io/ +## Using AI tools + +If you use AI tools to help draft issues, PRs, or comments, please +review [`docs/AI-TOOLS.md`](AI-TOOLS.md) for our guidelines. + ## Finding an issue to work on We try to keep a variety of issues tagged with