diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 37b8d357c87..642c295e409 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,20 @@ +### Description + +### Checklist + - [ ] Closes #xxxx - [ ] Tests added - [ ] User visible changes (including notable bug fixes) are documented in `whats-new.rst` - [ ] New functions/methods are listed in `api.rst` + +### AI Disclosure + + + +- [ ] This PR contains AI-generated content. + - [ ] I have tested any AI-generated content in my PR. + - [ ] I take responsibility for any AI-generated content in my PR. + + Tools: {e.g., Claude, Codex, GitHub Copilot, ChatGPT, etc.} diff --git a/.github/workflows/ci-additional.yaml b/.github/workflows/ci-additional.yaml index 067a7d01a65..fda7151055e 100644 --- a/.github/workflows/ci-additional.yaml +++ b/.github/workflows/ci-additional.yaml @@ -45,7 +45,7 @@ jobs: steps: - uses: actions/checkout@v6 - - uses: Parcels-code/pixi-lock/create-and-cache@a9aee67fa67426e6b0297fa5bef80600572be153 + - uses: Parcels-code/pixi-lock/create-and-cache@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 id: pixi-lock - uses: actions/upload-artifact@v7 with: @@ -72,7 +72,7 @@ jobs: echo "TODAY=$(date +'%Y-%m-%d')" >> $GITHUB_ENV - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 @@ -110,7 +110,7 @@ jobs: with: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 @@ -155,7 +155,7 @@ jobs: with: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 @@ -204,7 +204,7 @@ jobs: fetch-depth: 0 - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 @@ -254,7 +254,7 @@ jobs: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 @@ -302,7 +302,7 @@ jobs: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index ad1f1bee745..c154a71bf29 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -45,7 +45,7 @@ jobs: steps: - uses: actions/checkout@v6 - - uses: Parcels-code/pixi-lock/create-and-cache@a9aee67fa67426e6b0297fa5bef80600572be153 + - uses: Parcels-code/pixi-lock/create-and-cache@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 id: pixi-lock - uses: actions/upload-artifact@v7 with: @@ -96,7 +96,7 @@ jobs: with: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 diff --git a/.github/workflows/hypothesis.yaml b/.github/workflows/hypothesis.yaml index 8adfd1b8912..39989344e28 100644 --- a/.github/workflows/hypothesis.yaml +++ b/.github/workflows/hypothesis.yaml @@ -52,7 +52,7 @@ jobs: pixi-version: ${{ steps.pixi-lock.outputs.pixi-version }} steps: - uses: actions/checkout@v6 - - uses: Parcels-code/pixi-lock/create-and-cache@a9aee67fa67426e6b0297fa5bef80600572be153 + - uses: Parcels-code/pixi-lock/create-and-cache@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 id: pixi-lock - uses: actions/upload-artifact@v7 with: @@ -78,7 +78,7 @@ jobs: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 diff --git a/.github/workflows/upstream-dev-ci.yaml b/.github/workflows/upstream-dev-ci.yaml index e2d7375b962..c5a9a59e03f 100644 --- a/.github/workflows/upstream-dev-ci.yaml +++ b/.github/workflows/upstream-dev-ci.yaml @@ -59,7 +59,7 @@ jobs: pixi-version: ${{ steps.pixi-lock.outputs.pixi-version }} steps: - uses: actions/checkout@v6 - - uses: Parcels-code/pixi-lock/create-and-cache@a9aee67fa67426e6b0297fa5bef80600572be153 + - uses: Parcels-code/pixi-lock/create-and-cache@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 id: pixi-lock - uses: actions/upload-artifact@v7 with: @@ -84,7 +84,7 @@ jobs: with: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 @@ -137,7 +137,7 @@ jobs: fetch-depth: 0 # Fetch all history for all branches and tags. - name: Restore cached pixi lockfile - uses: Parcels-code/pixi-lock/restore@a9aee67fa67426e6b0297fa5bef80600572be153 + uses: Parcels-code/pixi-lock/restore@38495788b79a5ff26009aecc15daa9a8310b8832 # v0.1.0 with: cache-key: ${{ needs.cache-pixi-lock.outputs.cache-key }} - uses: prefix-dev/setup-pixi@v0.9.4 diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 00000000000..209be614c59 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1 @@ +doc/contribute/ai-policy.md diff --git a/doc/contribute/ai-policy.md b/doc/contribute/ai-policy.md new file mode 100644 index 00000000000..2bf6224d933 --- /dev/null +++ b/doc/contribute/ai-policy.md @@ -0,0 +1,88 @@ + + +# AI Usage Policy + +**Note:** Some Xarray developers use AI tools as part of our development workflow. +We assume this is now common. Tools, patterns, and norms are evolving fast — this +policy aims to avoid restricting contributors' choice of tooling while ensuring that: + +- Reviewers are not overburdened +- Contributions can be maintained +- The submitter can vouch for and explain all changes +- Developers can acquire new skills[^1] + +To that end this policy applies regardless of whether the code was written by hand, with +AI assistance, or generated entirely by an AI tool. + +[^1]: + Over-reliance on AI tools has been shown to + [hinder skill formation amongst software developers](https://arxiv.org/abs/2601.20245). + +## Core Principle: Changes + +If you submit a pull request, you are responsible for understanding and having fully reviewed +the changes. You must be able to explain why each change is correct[^2] and how it fits into +the project. Strive to minimize changes to ease the burden on reviewers — avoid +including unnecessary or loosely related changes. + +[^2]: + You may also open a draft PR with changes in order to discuss and receive feedback on the + best approach if you are not sure what the best way forward is. + +## Core Principle: Communication + +PR descriptions, issue comments, and review responses must be your own words. The +substance and reasoning must come from you. Do not paste AI-generated text as +comments or review responses. Please attempt to be concise. + +PR descriptions should follow the provided template. + +Using AI to improve the language of your writing (grammar, phrasing, spelling, etc.) is +acceptable. Be careful that it does not introduce inaccurate details in the process. + +Maintainers reserve the right to delete or hide comments that violate our AI policy or code of conduct. + +## Code and Tests + +### Review Every Line + +You must have personally reviewed and understood all changes before submitting. + +If you used AI to generate code, you are expected to have read it critically and +tested it. As with a hand-written PR, the description should explain the approach +and reasoning behind the changes. Do not leave it to reviewers to figure out what +the code does and why. + +#### Not Acceptable + +> I pointed an agent at the issue and here are the changes + +> This is what Claude came up with. 🤷 + +#### Acceptable + +> I iterated multiple times with an agent to produce this. The agent wrote the code at my direction, +> and I have fully read and validated the changes. + +> I pointed an agent at the issue and it generated a first draft. I reviewed the changes thoroughly and understand the implementation well. + +### Large AI-Assisted Contributions + +Generating code with agents is fast and easy. Reviewing it is not. Making a PR with a large diff +shifts the burden from the contributor to the reviewer. To guard against this asymmetry: + +If you are planning a large AI-assisted contribution (e.g., a significant refactor, a +framework migration, or a new subsystem), **open an issue first** to discuss the scope +and approach with maintainers. This helps us decide if the change is worthwhile, how +it should be structured, and any other important decisions. + +Maintainers reserve the right to close PRs where the scope makes meaningful review +impractical, or when they suspect this policy has been violated. Similarly they may request +that large changes be broken into smaller, reviewable pieces. + +## Documentation + +The same core principles apply to both code and documentation. You must review the result +for accuracy and are ultimately responsible for all changes made. Xarray has domain-specific +semantics that AI tools frequently get wrong. Do not submit documentation that you +haven't carefully read and verified. diff --git a/doc/contribute/contributing.rst b/doc/contribute/contributing.rst index 4b1dd12af2e..a0ddf551833 100644 --- a/doc/contribute/contributing.rst +++ b/doc/contribute/contributing.rst @@ -15,7 +15,7 @@ Overview We welcome your skills and enthusiasm at the xarray project!. There are numerous opportunities to contribute beyond just writing code. All contributions, including bug reports, bug fixes, documentation improvements, enhancement suggestions, -and other ideas are welcome. +and other ideas are welcome. LLM generated contributions are welcome, but they must follow :doc:`our AI policy `. If you have any questions on the process or how to fix something feel free to ask us! The recommended places to ask questions are `GitHub Discussions `_ diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst index 2501376467d..e5de049fcdb 100644 --- a/doc/contribute/index.rst +++ b/doc/contribute/index.rst @@ -13,6 +13,7 @@ In this section you will also find documentation on the internal organization of :hidden: contributing + ai-policy ../internals/index ../roadmap ../whats-new diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 81d901068b3..ca172a3a85a 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -120,6 +120,8 @@ Bug Fixes Documentation ~~~~~~~~~~~~~ +- Add AI policy (:pull:`11257`). + By `Nick Hodgskin `_. - Update documentation and team guide to promote Zulip. Remove mentions of Discord (:pull:`11246`, :pull:`11254`). By `Nick Hodgskin `_. - Fix typos (:pull:`11180`, :pull:`11181`, :pull:`11182`, :pull:`11185`, :pull:`11186`). @@ -136,9 +138,9 @@ Performance Internal Changes ~~~~~~~~~~~~~~~~ + - Add script for linting of public docstrings according to numpydoc (:pull:`11121`). By `Nick Hodgskin `_. - - Add stubtest configuration and allowlist for validating type annotations against runtime behavior. This enables CI integration for type stub validation and helps prevent type annotation regressions (:issue:`11086`).