DOC: AI Usage Policy (draft for discussion)

[aladinor]

Summary

Opens for community discussion an AI Usage Policy for xradar, adapted from xarray's AI Usage Policy with two xradar-specific additions.

This is a draft so the whole community can chime in before we merge. Continues the discussion started in #354.

What's in the draft

• docs/ai_policy.md — full policy (attribution to xarray in the preamble).
• CONTRIBUTING.md — short pointer section between "Types of Contributions" and "Get Started!" linking to the full doc.
• docs/index.md — new ai_policy entry in the toctree.
• docs/history.md — Development entry (PR-number placeholder to update once this lands).

Structure

The policy mirrors xarray's structure so folks coming from that ecosystem find it familiar:

1. Core Principle: Changes — you are responsible for every line.
2. Core Principle: Communication — PR descriptions and review replies must be your own words.
3. Code and Tests
   • Review Every Line (with Not-Acceptable / Acceptable examples).
   • Prefer Small PRs and Open an Issue First — framed by review burden, not line count. A 100-line AI-generated change can be just as hard to review as a 2,000-line one. Strongly encouraged: open an issue before any non-trivial AI-assisted contribution so maintainers can validate scope and structure before any code is written.
   • CI, Packaging, and Dependency Changes — new section. GitHub Actions, dependencies, pyproject.toml / environment.yml / pre-commit config, and security-sensitive areas require an issue-first discussion; AI is not a reliable guide to the security or maintenance implications of a new dependency. Raised by @zssherman in MNT: Improve Contributing Guide #354.
4. Documentation — names xradar's domain specifics (CfRadial2/FM301, WMO Manual on Codes, format ICDs).
5. Disclosing AI Usage — new section. Recommends (not requires) noting the tool/model and version in the PR description when AI was used. Also raised by @zssherman.

Discussion points

This is a policy document — language matters more than usual. Feedback especially welcome on:

• Whether the "CI / Packaging / Dependency" framing is the right level of strictness.
• Whether to require (not just recommend) disclosing the AI tool/model.
• Whether the examples in "Not Acceptable / Acceptable" need xradar-specific replacements.
• Whether the file should live at docs/ai_policy.md or somewhere else (e.g. a new docs/contribute/ subfolder to mirror xarray's layout).

CC: @kmuehlbauer @syedhamidali @mgrover1 @egouden @zssherman @scollis @rcjackson @jrobrien91

Test plan

• File renders cleanly in GitHub's markdown preview.
• Sphinx build picks up ai_policy in the toctree (cd docs && make html).
• Any maintainer happy to sanity-check the policy language before we take it out of draft.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.85%. Comparing base (464b4dc) to head (0bd4d9d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #363   +/-   ##
=======================================
  Coverage   93.85%   93.85%           
=======================================
  Files          28       28           
  Lines        6165     6165           
=======================================
  Hits         5786     5786           
  Misses        379      379           

Flag	Coverage Δ
notebooktests	0.00% <ø> (ø)
unittests	93.85% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.