AI Usage Policy#

Version 0.1#

We reserve the right to update this policy at anytime#

Some Py-ART 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 and xradar AI Usage Policy and aligns with similar efforts across the scientific Python ecosystem, with pyart-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#

The main summary of your PR descriptions, issue comments, and review responses must be your own words and should not be fully AI. The substance and reasoning must come from you. Do not paste AI-generated text as comments or review responses. Please attempt to be concise. You may use AI if assistance is required to improve the language of your writing with small or simple changes such as (grammar, phrasing, spelling, etc.) is acceptable. Be careful that it does not introduce inaccurate details in the process.

PR descriptions should follow the provided PR template when the PR is opened on GitHub.

Maintainers reserve the right to delete or hide comments that violate our AI policy or code of conduct.

Privacy and Data Protection#

Contributors should ensure that the submitted code, commits, pull request messages and more should not contain any private data, proprietary code, or restricted information.

Company Policy#

Many AI tools train or retain data that is submitted to the prompt. Many employers only approve tools that do not train or retrain on such data. Contributors should validate that the tool they use is acceptable to use under their employer’s policy before feeding in the code or data.

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. Providing a jupyter notebook as well for showcasing the new code is appreciated. Unit tests should be provided as well for new code or functionality.

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, understand the implementation well and tested the changes.

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 fully AI generated Issues or pull request. When opening an issue, the issue can not be open via an agent. Pull requests also can not be open by an AI agent. 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 Py-ART — 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. Py-ART has domain-specific semantics such as radar 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 (example below). 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.

Example of filling out the AI Disclosure in the PR Submission#

If AI tools were used, complete this section.

  • AI used: yes

  • Model/tooling: Claude Opus 5

  • Tasks delegated to AI: Given the VAP technical document and pointing to the Heffter and Liu Liang techniques, claude was asked to develop the bulk richardson number retrieval. Iteration with claude was performed to use the Metpy constants for saturation vapor pressure calculation.

  • Manual verification performed: Manual verification against test files and manual creation of new retrieval example to display all sonde PBLH schemes on top of a SGP sonde profile. Manually reconfigured naming convention for ease of review.