|
| 1 | +<!-- markdownlint-disable MD013 --> |
| 2 | + |
| 3 | +# AI Usage Policy |
| 4 | + |
| 5 | +**Note:** Some Xarray developers use AI tools as part of our development workflow. |
| 6 | +We assume this is now common. Tools, patterns, and norms are evolving fast — this |
| 7 | +policy aims to avoid restricting contributors' choice of tooling while ensuring that: |
| 8 | + |
| 9 | +- Reviewers are not overburdened |
| 10 | +- Contributions can be maintained |
| 11 | +- The submitter can vouch for and explain all changes |
| 12 | +- Developers can acquire new skills[^1] |
| 13 | + |
| 14 | +To that end this policy applies regardless of whether the code was written by hand, with |
| 15 | +AI assistance, or generated entirely by an AI tool. |
| 16 | + |
| 17 | +[^1]: |
| 18 | + Over-reliance on AI tools has been shown to |
| 19 | + [hinder skill formation amongst software developers](https://arxiv.org/abs/2601.20245). |
| 20 | + |
| 21 | +## Core Principle: Changes |
| 22 | + |
| 23 | +If you submit a pull request, you are responsible for understanding and having fully reviewed |
| 24 | +the changes. You must be able to explain why each change is correct[^2] and how it fits into |
| 25 | +the project. Strive to minimize changes to ease the burden on reviewers — avoid |
| 26 | +including unnecessary or loosely related changes. |
| 27 | + |
| 28 | +[^2]: |
| 29 | + You may also open a draft PR with changes in order to discuss and receive feedback on the |
| 30 | + best approach if you are not sure what the best way forward is. |
| 31 | + |
| 32 | +## Core Principle: Communication |
| 33 | + |
| 34 | +PR descriptions, issue comments, and review responses must be your own words. The |
| 35 | +substance and reasoning must come from you. Do not paste AI-generated text as |
| 36 | +comments or review responses. Please attempt to be concise. |
| 37 | + |
| 38 | +PR descriptions should follow the provided template. |
| 39 | + |
| 40 | +Using AI to improve the language of your writing (grammar, phrasing, spelling, etc.) is |
| 41 | +acceptable. Be careful that it does not introduce inaccurate details in the process. |
| 42 | + |
| 43 | +Maintainers reserve the right to delete or hide comments that violate our AI policy or code of conduct. |
| 44 | + |
| 45 | +## Code and Tests |
| 46 | + |
| 47 | +### Review Every Line |
| 48 | + |
| 49 | +You must have personally reviewed and understood all changes before submitting. |
| 50 | + |
| 51 | +If you used AI to generate code, you are expected to have read it critically and |
| 52 | +tested it. As with a hand-written PR, the description should explain the approach |
| 53 | +and reasoning behind the changes. Do not leave it to reviewers to figure out what |
| 54 | +the code does and why. |
| 55 | + |
| 56 | +#### Not Acceptable |
| 57 | + |
| 58 | +> I pointed an agent at the issue and here are the changes |
| 59 | +
|
| 60 | +> This is what Claude came up with. 🤷 |
| 61 | +
|
| 62 | +#### Acceptable |
| 63 | + |
| 64 | +> I iterated multiple times with an agent to produce this. The agent wrote the code at my direction, |
| 65 | +> and I have fully read and validated the changes. |
| 66 | +
|
| 67 | +> I pointed an agent at the issue and it generated a first draft. I reviewed the changes thoroughly and understand the implementation well. |
| 68 | +
|
| 69 | +### Large AI-Assisted Contributions |
| 70 | + |
| 71 | +Generating code with agents is fast and easy. Reviewing it is not. Making a PR with a large diff |
| 72 | +shifts the burden from the contributor to the reviewer. To guard against this asymmetry: |
| 73 | + |
| 74 | +If you are planning a large AI-assisted contribution (e.g., a significant refactor, a |
| 75 | +framework migration, or a new subsystem), **open an issue first** to discuss the scope |
| 76 | +and approach with maintainers. This helps us decide if the change is worthwhile, how |
| 77 | +it should be structured, and any other important decisions. |
| 78 | + |
| 79 | +Maintainers reserve the right to close PRs where the scope makes meaningful review |
| 80 | +impractical, or when they suspect this policy has been violated. Similarly they may request |
| 81 | +that large changes be broken into smaller, reviewable pieces. |
| 82 | + |
| 83 | +## Documentation |
| 84 | + |
| 85 | +The same core principles apply to both code and documentation. You must review the result |
| 86 | +for accuracy and are ultimately responsible for all changes made. Xarray has domain-specific |
| 87 | +semantics that AI tools frequently get wrong. Do not submit documentation that you |
| 88 | +haven't carefully read and verified. |
0 commit comments