DOC: AI Usage Policy (draft for discussion)

CONTRIBUTING.md

@@ -42,6 +42,15 @@ If you are proposing a feature:
 * Remember that this is a volunteer-driven project, and that contributions
   are welcome :)
 
+## AI Usage Policy
+
+xradar contributors may use AI tools as part of their workflow. Please read the
+[AI Usage Policy](https://github.com/openradar/xradar/blob/main/docs/ai_policy.md)
+before submitting an AI-assisted contribution. In short: you are responsible
+for every line of code in your PR, PR descriptions and review replies must be
+your own words, and large AI-assisted changes — as well as CI, packaging, and
+dependency changes — should start with an issue rather than a surprise diff.
+
 ## Get Started!
 
 Ready to contribute? Here's how to set up `xradar` for local development.

docs/ai_policy.md

@@ -0,0 +1,136 @@
+<!-- markdownlint-disable MD013 -->
+
+# AI Usage Policy
+
+Some xradar contributors and maintainers use AI tools as part of their 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
+
+This policy applies regardless of whether the code was written by hand, with AI
+assistance, or generated entirely by an AI tool. It is adapted from the
+[xarray AI Usage Policy](https://github.com/pydata/xarray/blob/main/doc/contribute/ai-policy.md)
+and aligns with similar efforts across the scientific Python ecosystem, with
+xradar-specific additions for CI, packaging, and dependency changes.
+
+## 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 and how it fits into the project. Strive to minimize changes to ease the
+burden on reviewers — avoid including unnecessary or loosely related changes.
+
+If you are unsure about the best way forward, open a draft PR and use it to
+discuss the approach with maintainers before expanding the scope.
+
+## 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.
+
+### Prefer Small PRs and Open an Issue First
+
+Generating code with agents is fast and easy. Reviewing it is not. Any PR —
+hundreds of lines or just tens — that is hard to review shifts the burden from
+the contributor to the reviewer. Line count is not the only criterion; what
+matters is how confidently a reviewer can follow the change end-to-end.
+
+**Prefer small, focused PRs over one large one.** A series of small,
+independently reviewable PRs — each tied to a clear issue — is almost always
+easier to review, merge, and revert than a single larger change. If an
+AI-assisted contribution can be decomposed into smaller pieces, please do so.
+
+**Strongly encouraged: open an issue first** for any non-trivial AI-assisted
+contribution (for example, a refactor, a framework migration, a new subsystem,
+or any change whose review burden is non-obvious at a glance). The issue
+should describe the motivation, the proposed approach, and the expected
+scope. Maintainers will use it to confirm the work is a good fit for the
+project, surface concerns early, and agree on how the change should be
+structured **before any code is written**. This prevents the common AI-era
+pattern of a surprise diff that nobody asked for and nobody wants to review.
+
+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.
+
+### CI, Packaging, and Dependency Changes
+
+Changes that affect project infrastructure have a broader blast radius than a
+typical feature or bug fix. For this class of change — including, but not
+limited to:
+
+- GitHub Actions workflows, CI configuration, or release workflows
+- Adding, removing, or bumping dependencies (runtime or development)
+- Changes to `pyproject.toml`, `environment.yml`, `requirements*.txt`, or
+  `.pre-commit-config.yaml`
+- Security-sensitive areas (credentials, file I/O path handling, subprocess
+  invocation)
+
+we ask that contributors **open an issue first** to discuss the motivation and
+scope before submitting a PR, and explicitly note whether AI tools were used in
+the proposed change. AI tools are not a reliable guide to the security,
+licensing, or maintenance implications of adding a new dependency, and xradar —
+like other scientific open-source projects — is a potential target for
+supply-chain-style contributions. Maintainers may ask that AI not be used for
+these changes, or that an issue-first discussion happen before any code is
+generated.
+
+## 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.
+xradar has domain-specific semantics — radar data conventions, CfRadial2/FM301
+terminology, format-specific ICD quirks — that AI tools frequently get wrong.
+Do not submit documentation that you haven't carefully read and verified
+against authoritative references (e.g. the WMO Manual on Codes, format ICDs,
+or the relevant vendor documentation).
+
+## Disclosing AI Usage
+
+When you use AI tools to help with a contribution, we **recommend** noting this
+in the PR description, including the tool or model name and version where it is
+known (for example: "Claude Opus 4.7", "Cursor with GPT-5.1"). This is not
+required, but it helps reviewers calibrate their attention and helps the
+community develop shared intuition about where AI tools work well and where
+they struggle on radar-data work.

docs/history.md

@@ -3,6 +3,7 @@
 
 ## Development
 
+* DOC: Add AI Usage Policy (``docs/ai_policy.md``) adapted from xarray's policy, with xradar-specific guidance for CI, packaging, and dependency changes ({pull}`363`) by [@aladinor](https://github.com/aladinor)
 * MNT: Clarify contributor, team-member, and maintainer roles in the contributing guide, including the pathway to greater project involvement ({issue}`341`) by [@kmuehlbauer](https://github.com/kmuehlbauer), ({pull}`354`) by [@syedhamidali](https://github.com/syedhamidali)
 * ADD: ``open_cfradial2_datatree`` reader with grouped CfRadial2 compatibility normalization for common FM301/CfRadial2 naming differences ({issue}`93`, {issue}`287`), ({pull}`349`) by [@syedhamidali](https://github.com/syedhamidali)
 * ENH: Move station coordinates (``latitude``, ``longitude``, ``altitude``) to root node as coordinates for DataTree coordinate inheritance ({issue}`331`, {pull}`333`) by [@aladinor](https://github.com/aladinor)

docs/index.md

@@ -20,6 +20,7 @@ html_theme.sidebar_secondary.remove: true
 installation
 usage
 contributing
+ai_policy
 authors
 history
 reference