Skip to content

Commit 14739a5

Browse files
ianhirabernatdcherian
authored
AI/Contributing policy (#1766)
## Description Adds an AI usage policy so that we have something to refer to going forward. Also a first effort at codifying where we feel the boundary should be. I tried to strike a balance of recognizing that we use agents quite successfully on this project, while trying to disallow pathological applications. I did want to leave an escape hatch of a large AI generated PR for use in large restructuring PRs such as - xpublish-community/xpublish-opendap#100 or for example anythinng we may do for converting to mystmd. With a requirement that there be discussion prior to opening. Ultimately the core of this has to come down to honest an open communication from the submitter and the reviewer. ## AI Usage Disclosure - [x] AI tools were used in this contribution I used claude to help gather and research other proejct AI policies. I also used claude for spell and grammar checking as well stuff like the mkdocs toctree. - [Matplotlib — Restrictions on Generative AI Usage](https://matplotlib.org/devdocs/devel/contribute.html#generative-ai) - [melissawm/open-source-ai-contribution-policies](https://github.com/melissawm/open-source-ai-contribution-policies) - [Scientific Python blog — Community Considerations Around AI Contributions](https://blog.scientific-python.org/scientific-python/community-considerations-around-ai/) --------- Co-authored-by: Ryan Abernathey <[email protected]> Co-authored-by: Deepak Cherian <[email protected]>
1 parent 7d45ec6 commit 14739a5

5 files changed

Lines changed: 87 additions & 0 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<!-- Please review our AI & contribution guidelines: https://icechunk.io/en/latest/ai-policy/ -->
2+
3+
## Description
4+
5+
<!-- Describe your changes and the reasoning behind them. -->

‎AI_USAGE_POLICY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
icechunk-python/docs/docs/ai-policy.md

‎icechunk-python/docs/docs/ai-policy.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
<!-- markdownlint-disable MD013 -->
2+
3+
# AI Usage Policy
4+
5+
**Note:** Some Icechunk developers use AI tools as part of our development workflow.
6+
We assume this is now common. Tools, patterns, and norms are evolving fast — this
7+
policy aims to avoid restricting contributors' choice of tooling while ensuring that:
8+
9+
- Reviewers are not overburdened
10+
- Contributions can be maintained
11+
- The submitter can vouch for and explain all changes
12+
13+
To that end this policy applies regardless of whether the code was written by hand, with
14+
AI assistance, or generated entirely by an AI tool.
15+
16+
## Core Principle: Changes
17+
18+
If you submit a pull request, you are responsible for understanding and having fully reviewed
19+
the changes. You must be able to explain why each change is correct[^1] and how it fits into
20+
the project. Strive to minimize changes to ease the burden on reviewers — avoid
21+
including unnecessary or loosely related changes.
22+
23+
[^1]: You may also open a draft PR with changes in order to discuss and receive feedback on the
24+
best approach if you are not sure what the best way forward is.
25+
26+
## Core Principle: Communication
27+
28+
PR descriptions, issue comments, and review responses must be your own words. The
29+
substance and reasoning must come from you. Do not paste AI-generated text as
30+
comments or review responses. Please attempt to be concise.
31+
32+
Using AI to improve the language of your writing (grammar, phrasing, spelling, etc.) is
33+
acceptable. Be careful that it does not introduce inaccurate details in the process.
34+
35+
## Code and Tests
36+
37+
### Review Every Line
38+
39+
You must have personally reviewed and understood all changes before submitting.
40+
41+
If you used AI to generate code, you are expected to have read it critically and
42+
tested it. As with a hand-written PR, the description should explain the approach
43+
and reasoning behind the changes. Do not leave it to reviewers to figure out what
44+
the code does and why.
45+
46+
#### Not Acceptable
47+
48+
> I pointed an agent at the issue and here are the changes
49+
50+
> This is what Claude came up with. 🤷
51+
52+
#### Acceptable
53+
54+
> I iterated multiple times with an agent to produce this. The agent wrote the code at my direction,
55+
> and I have fully read and validated the changes.
56+
57+
> I pointed an agent at the issue and it generated a first draft. I reviewed the changes thoroughly and understand the implementation well.
58+
59+
### Large AI-Assisted Contributions
60+
61+
Generating code with agents is fast and easy. Reviewing it is not. Making a PR with a large diff
62+
shifts the burden from the contributor to the reviewer. To guard against this asymmetry:
63+
64+
If you are planning a large AI-assisted contribution (e.g., a significant refactor, a
65+
framework migration, or a new subsystem), **open an issue first** to discuss the scope
66+
and approach with maintainers. This helps us decide if the change is worthwhile, how
67+
it should be structured, and any other important decisions.
68+
69+
Maintainers reserve the right to close PRs where the scope makes meaningful review
70+
impractical, or when they suspect this policy has been violated. Similarly they may request
71+
that large changes be broken into smaller, reviewable pieces.
72+
73+
## Documentation
74+
75+
The same core principles apply to both code and documentation You must review the result
76+
for accuracy and are ultimately responsible for all changes made. Icechunk has domain-specific
77+
semantics that AI tools frequently get wrong. Do not submit documentation that you
78+
haven't carefully read and verified.

‎icechunk-python/docs/docs/contributing.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ Icechunk is an open source (Apache 2.0) project and welcomes contributions in th
1717
- Documentation improvements - [open a GitHub pull request](https://github.com/earth-mover/icechunk/pulls)
1818
- Bug fixes and enhancements - [open a GitHub pull request](https://github.com/earth-mover/icechunk/pulls)
1919

20+
🤖 Please review our [AI Usage Policy](ai-policy.md), which also serves as contribution guidelines, before submitting pull requests.
21+
2022
## Development
2123

2224
This guide describes the local development workflow for:

‎icechunk-python/docs/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,4 +226,5 @@ nav:
226226
- Python API Reference: reference.md
227227
- Icechunk Rust: icechunk-rust.md
228228
- Contributing: contributing.md
229+
- AI Usage Policy: ai-policy.md
229230
- Migrate to 1.0: migration.md

0 commit comments

Comments
 (0)