From 184b265663d03c9c2c4dfdffde57f9114d3d744b Mon Sep 17 00:00:00 2001 From: zssherman Date: Thu, 6 Aug 2026 11:26:50 -0500 Subject: [PATCH 1/2] DOC: Add ai_policy to ACT. --- AI_POLICY.md | 158 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 AI_POLICY.md diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 0000000000..a228b63232 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1,158 @@ +# AI Usage Policy +# Version 0.1 + +## We reserve the right to update this policy at anytime + +Some ACT 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 [xradar AI Usage Policy]() +and aligns with similar efforts across the scientific Python ecosystem, with +ACT-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. + +## Copyright + +All code in ACT is released under the BSD 3-clause copyright license. +Contributors to ACT license their code under the same license when it is +included in ACT's version control repository. That means contributors must +own the copyright of any code submitted to ACT or must include the +BSD 3-clause compatible open source license(s) associated with the submitted +code in the patch. Code generated by AI may infringe on copyright and it is the +submitter’s responsibility to not infringe. We reserve the right to reject any +pull requests, AI-generated or not, where the copyright is in question. + +## 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. For example, for changes touching +retrievals, corrections, or any physical calculations, reviewing the code +is not sufficient β€” validate the output against a reference dataset, a +published result, or the prior implementation, and say so in the PR +description. + +#### 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. + +**No AI generated Issues or pull request reviews.** When opening an issue, +the issue can not be open via an agent. Pull requests reviews also can not +be AI generated. Doing so, would defeat the purpose of discussing AI +generated or assisted code by involving a real person to ensure these +changes are correct and meaningful. + +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 reach 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 ACT β€” +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. +ACT has domain-specific semantics such as instrument data conventions, terminology +and more 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, CF conventions for radar and lidar, 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. From 2847db8683a989203d3f526b25497036f13cc1a3 Mon Sep 17 00:00:00 2001 From: zssherman Date: Mon, 24 Aug 2026 14:05:35 -0500 Subject: [PATCH 2/2] DOC: Suggested changes. --- AI_POLICY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AI_POLICY.md b/AI_POLICY.md index a228b63232..1a03cd3b85 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -155,4 +155,4 @@ 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. +they struggle on atmospheric datasets.