From bf86884e5a80e8142486dd5f671366b302f7b5ad Mon Sep 17 00:00:00 2001 From: aladinor Date: Mon, 20 Apr 2026 12:03:07 -0500 Subject: [PATCH 1/3] DOC: Add AI Usage Policy Adds docs/ai_policy.md, adapted from xarray's policy (doc/contribute/ai-policy.md) with attribution, and xradar-specific additions: - "CI, Packaging, and Dependency Changes" subsection requiring an issue-first discussion before any AI-assisted PR touches GitHub Actions, dependencies, pyproject/environment files, pre-commit config, or security-sensitive areas. Rationale: supply-chain risk, raised by @zssherman in #354. - "Disclosing AI Usage" section recommending (not requiring) that PR descriptions note the tool/model and version when AI was used. Also: - Short "AI Usage Policy" pointer section in CONTRIBUTING.md linking to the full policy. - Adds ai_policy to docs/index.md toctree. - History entry (PR number placeholder). Discussed in #354. --- CONTRIBUTING.md | 9 ++++ docs/ai_policy.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++ docs/history.md | 1 + docs/index.md | 1 + 4 files changed, 138 insertions(+) create mode 100644 docs/ai_policy.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da5bc26c..cf72bef2 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/docs/ai_policy.md b/docs/ai_policy.md new file mode 100644 index 00000000..39b73036 --- /dev/null +++ b/docs/ai_policy.md @@ -0,0 +1,127 @@ + + +# 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. + +### 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. + +### 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. diff --git a/docs/history.md b/docs/history.md index 5a6059af..ff1c4a0e 100644 --- a/docs/history.md +++ b/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}`NNN`) 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) diff --git a/docs/index.md b/docs/index.md index 3c328ab8..c3de9cc9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,6 +20,7 @@ html_theme.sidebar_secondary.remove: true installation usage contributing +ai_policy authors history reference From 9e15687c2c8809d11a14cedac2d21482affa2529 Mon Sep 17 00:00:00 2001 From: aladinor Date: Mon, 20 Apr 2026 12:34:24 -0500 Subject: [PATCH 2/3] DOC: AI policy: frame PR size by review burden, not line count Reframe "Large AI-Assisted Contributions" -> "Prefer Small PRs and Open an Issue First". Drop the absolute 2,000-line example in favor of review burden as the criterion (a 100-line change can also be too dense to review in isolation). Add an explicit "strongly encouraged" issue-first step so maintainers can validate scope and structure before any code is written. --- docs/ai_policy.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/ai_policy.md b/docs/ai_policy.md index 39b73036..35950974 100644 --- a/docs/ai_policy.md +++ b/docs/ai_policy.md @@ -68,22 +68,31 @@ figure out what the code does and why. > 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. +### 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. +Similarly they may request that large changes be broken into smaller, +reviewable pieces. ### CI, Packaging, and Dependency Changes From 0bd4d9d0f5ae16828640313873329e3640bf540f Mon Sep 17 00:00:00 2001 From: aladinor Date: Mon, 20 Apr 2026 12:35:30 -0500 Subject: [PATCH 3/3] DOC: history.md: link AI Usage Policy entry to PR #363 --- docs/history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/history.md b/docs/history.md index ff1c4a0e..94cc0ddb 100644 --- a/docs/history.md +++ b/docs/history.md @@ -3,7 +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}`NNN`) by [@aladinor](https://github.com/aladinor) +* 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)