Skip to content

Commit 3ecafce

Browse files
SplatcrafterSplatcrafter
authored
Merge pull request #240 from aether-framework/feature/adding-mandatory-docs
Introduce AI guidelines and automate PR target retargeting
2 parents 948a6ed + cc24351 commit 3ecafce

5 files changed

Lines changed: 376 additions & 5 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,15 @@ Closes #…
2424
## Breaking Changes
2525
Describe any breaking changes or migration steps.
2626

27+
## AI Disclosure
28+
- [ ] This PR includes AI-generated or AI-assisted content
29+
- If checked, describe which parts and which AI tool was used: …
30+
31+
See [AI Usage Guidelines](../../AI_USAGE.md) for details.
32+
2733
## Checklist
2834
- [ ] Code follows project conventions
2935
- [ ] Public APIs are documented
3036
- [ ] Tests cover new behavior
3137
- [ ] No unnecessary dependencies added
38+
- [ ] AI usage disclosed (if applicable)

‎.github/workflows/retarget-pr-to-develop.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Retarget PRs from main to develop
2+
3+
on:
4+
pull_request:
5+
types: [opened]
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
pull-requests: write
11+
12+
jobs:
13+
retarget:
14+
runs-on: ubuntu-latest
15+
if: ${{ !startsWith(github.head_ref, 'release/') }}
16+
steps:
17+
- name: Retarget PR to develop
18+
env:
19+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
20+
run: |
21+
echo "::notice::PR #${{ github.event.pull_request.number }} targets main from '${{ github.head_ref }}' — retargeting to develop."
22+
gh pr edit ${{ github.event.pull_request.number }} \
23+
--repo ${{ github.repository }} \
24+
--base develop
25+
26+
- name: Leave a comment explaining the retarget
27+
env:
28+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
29+
run: |
30+
gh pr comment ${{ github.event.pull_request.number }} \
31+
--repo ${{ github.repository }} \
32+
--body "$(cat <<'EOF'
33+
🔀 **This PR has been automatically retargeted from `main` to `develop`.**
34+
35+
In this project, `develop` is the integration branch for all feature and fix contributions. Only `release/*` branches may target `main` directly.
36+
37+
If this retarget was a mistake (e.g., you intended to create a release PR), please update the base branch manually.
38+
39+
See [CONTRIBUTING.md](../blob/develop/CONTRIBUTING.md) for details on our branching strategy.
40+
EOF
41+
)"

‎AI_USAGE.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# 🤖 AI Usage Guidelines
2+
3+
Aether Datafixers permits the use of AI tools in contributions — but under strict conditions. Transparency, quality, and human accountability are **non-negotiable**. This document defines the rules that all contributors and maintainers must follow when using AI-assisted tooling.
4+
5+
---
6+
7+
## 📋 Purpose & Scope
8+
9+
### Why This Policy Exists
10+
11+
AI coding assistants (GitHub Copilot, Claude, ChatGPT, Cursor, and others) are increasingly part of modern development workflows. **We welcome the responsible and transparent use of AI tools** to accelerate development while maintaining our high standards for **transparency**, **quality**, **security**, and **legal compliance**.
12+
13+
### Who This Applies To
14+
15+
- ✅ All **contributors** (external and internal) submitting code, documentation, or other content
16+
- ✅ All **maintainers** reviewing, merging, or creating contributions
17+
- ✅ **Automated AI agents** (e.g., `copilot-swe-agent[bot]`) that submit PRs directly
18+
19+
### What This Covers
20+
21+
This policy applies to all forms of contribution:
22+
23+
- Source code and tests
24+
- Documentation and Javadoc
25+
- Commit messages and PR descriptions
26+
- Issue comments and discussion posts
27+
- Code reviews and review comments
28+
- Configuration and CI/CD changes
29+
30+
---
31+
32+
## ⚖️ General Principles
33+
34+
1. **AI is a tool, humans are accountable.** AI does not author contributions — humans do. The person who submits AI-assisted work bears full responsibility for it.
35+
2. **Same quality bar — no exceptions.** AI-generated output must meet the exact same standards as human-written code: conventions, tests, documentation, and review.
36+
3. **Transparency is mandatory.** Disclosure of significant AI assistance is required, not optional. Honest disclosure is always better than concealment.
37+
4. **Quality and security over speed.** AI can accelerate development, but speed must never come at the expense of correctness, maintainability, or security.
38+
5. **When in doubt, write it yourself.** If you are unsure whether AI output is correct, secure, or license-compatible — do not submit it. Rewrite it by hand.
39+
40+
---
41+
42+
## ✅ Permitted Uses
43+
44+
AI tools may be used in the following areas, subject to the conditions listed:
45+
46+
| Use Case | Status | Conditions |
47+
|---------------------------------------|-----------|-------------------------------------------------------------------|
48+
| Code generation (features, bug fixes) | ✅ Allowed | Must be fully understood, tested, and reviewed by the contributor |
49+
| Test generation (JUnit 5 / AssertJ) | ✅ Allowed | Assertions and edge cases must be manually verified |
50+
| Documentation and Javadoc | ✅ Allowed | Must be factually accurate — AI may hallucinate API details |
51+
| Boilerplate and scaffolding | ✅ Allowed | Still requires review for project conventions |
52+
| Commit message drafting | ✅ Allowed | Must accurately describe the actual changes |
53+
| PR description drafting | ✅ Allowed | Must reflect the real changes, not AI assumptions |
54+
| Refactoring suggestions | ✅ Allowed | All existing tests must pass; behavior must be preserved |
55+
| Issue triage and response drafting | ✅ Allowed | Must be reviewed before posting |
56+
57+
**Important:** All permitted uses require [disclosure](#-disclosure-requirements) and are subject to [quality standards](#-quality-standards).
58+
59+
---
60+
61+
## 🚫 Restricted & Prohibited Uses
62+
63+
### 🏷️ Good First Issues — Learning First
64+
65+
Issues labeled **`good first issue`** are **strongly encouraged** to be completed **primarily without significant AI assistance**.
66+
67+
**Why:** Good first issues exist to help new contributors learn the codebase and ramp up through hands-on experience. They are intentionally kept simple. Solving them with your own effort lets you truly understand the project’s structure, patterns, and conventions — and keeps the opportunity fair for everyone who wants to make their first contribution through genuine learning.
68+
69+
If you are new to the project, embrace these issues as a learning opportunity. If you are experienced enough to use AI effectively, you are welcome to pick a more challenging issue instead.
70+
71+
> Contributors may still use AI for small suggestions or learning purposes, but the core solution should reflect personal understanding and effort.
72+
73+
### ⚠️ Restricted Uses
74+
75+
The following areas require **extra scrutiny and maintainer approval** before AI-assisted contributions are accepted:
76+
77+
- **Security-sensitive code** — Any code handling untrusted data through `DynamicOps`, cryptographic operations, or artifact signing. Must be thoroughly reviewed by a maintainer with security context. See [SECURITY.md](SECURITY.md).
78+
- **Public API design** — AI may suggest API shapes, but public API decisions must be made deliberately by maintainers. AI suggestions must not be accepted wholesale.
79+
- **Core optics and type system changes** — Changes to the optic hierarchy (`Lens`, `Prism`, `Iso`, `Affine`, `Traversal`) or the type system require deep domain understanding that AI tools may lack.
80+
- **CI/CD pipeline modifications** — Changes to GitHub Actions workflows, Maven profiles, or build configuration require maintainer review for security and correctness.
81+
82+
### 🚫 Prohibited Uses
83+
84+
The following uses of AI are **not permitted**:
85+
86+
- **AI as sole code reviewer** — Every PR must be reviewed and approved by at least one human maintainer. AI review tools may supplement but never replace human review.
87+
- **Submitting unreviewed AI output** — Copy-pasting AI-generated code without reading, understanding, and verifying it is prohibited. You must be able to explain every line you submit.
88+
- **Undisclosed significant AI usage** — Knowingly concealing significant AI assistance violates this policy. See [Accountability](#-accountability).
89+
- **AI-generated vulnerability reports** — Automated AI scanning to generate public vulnerability reports is prohibited. Follow the private disclosure process in [SECURITY.md](SECURITY.md).
90+
- **Bypassing project standards** — Using AI to circumvent tests, Checkstyle rules, or other quality gates is prohibited.
91+
- **AI for license or legal decisions** — AI tools must not be relied upon for license compatibility analysis, DCO compliance interpretation, or other legal matters.
92+
93+
---
94+
95+
## 📢 Disclosure Requirements
96+
97+
Disclosure of AI assistance is **mandatory**. This is the most important operational requirement of this policy.
98+
99+
### 🔎 When to Disclose
100+
101+
Disclosure is required whenever AI tools were used to **generate or substantially modify** code, documentation, or other contributions.
102+
103+
**Rule of thumb:** If the AI produced a block of code, a paragraph of text, or a test case that you then submitted — even if you edited it afterward — disclose it.
104+
105+
**Exempt:** Minor AI-assisted tasks such as IDE autocomplete suggestions, spell-checking, or grammar corrections do not require disclosure.
106+
107+
### 💬 In Commits
108+
109+
Use a `Co-Authored-By` trailer in your commit message:
110+
111+
```
112+
feat: Add field renaming support for nested types
113+
114+
Implemented recursive field renaming in NestedTypeFix with
115+
full test coverage.
116+
117+
Co-Authored-By: GitHub Copilot <noreply@github.com>
118+
Signed-off-by: Your Name <your.email@example.com>
119+
```
120+
121+
Common AI tool trailers:
122+
123+
```
124+
Co-Authored-By: GitHub Copilot <noreply@github.com>
125+
Co-Authored-By: Claude <noreply@anthropic.com>
126+
Co-Authored-By: ChatGPT <noreply@openai.com>
127+
```
128+
129+
For automated AI agents (e.g., `copilot-swe-agent[bot]`), the commit author field already serves as disclosure.
130+
131+
### 📝 In Pull Requests
132+
133+
1. Check the **AI Disclosure** checkbox in the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
134+
2. In the PR description, state **which parts** were AI-assisted and **which tool** was used.
135+
136+
Example:
137+
138+
```markdown
139+
**AI Disclosure:** The implementation in `NestedTypeFix.java` and its unit tests
140+
were generated with Claude and reviewed/modified by the contributor. The Javadoc
141+
was written manually.
142+
```
143+
144+
### 💭 In Issues and Discussions
145+
146+
When posting AI-generated analysis, suggestions, or responses, add a brief note:
147+
148+
> *This response was drafted with AI assistance.*
149+
150+
---
151+
152+
## 🔍 Quality Standards
153+
154+
### Code Quality
155+
156+
AI-generated code must meet the same standards as human-written code:
157+
158+
- ✅ Pass all existing tests (`mvn clean package`)
159+
- ✅ Include new tests for new behavior (JUnit 5 + AssertJ)
160+
- ✅ Follow project coding conventions (validated by Checkstyle)
161+
- ✅ Include proper Javadoc for all public API methods
162+
- ✅ Use JetBrains annotations (`@NotNull`, `@Nullable`) where appropriate
163+
- ✅ Use Guava `Preconditions` for argument validation
164+
- ✅ Maintain thread-safety invariants — Aether Datafixers types are immutable and thread-safe by design
165+
- ✅ Not introduce unnecessary dependencies
166+
167+
### Documentation Quality
168+
169+
AI-generated documentation must:
170+
171+
- ✅ Be **factually accurate** — AI tools frequently hallucinate API details, method signatures, and module names
172+
- ✅ Be **consistent** with existing documentation style and structure
173+
- ✅ Reference **correct** class, method, and module names
174+
- ✅ Not contradict existing documentation
175+
176+
### Understanding Requirement
177+
178+
Contributors must **understand** the code they submit. "The AI wrote it" is not a valid explanation for bugs, security issues, or convention violations. Reviewers may ask contributors to explain AI-generated code, and the contributor must be able to do so.
179+
180+
---
181+
182+
## 🔎 Review Process
183+
184+
AI-assisted PRs follow the same review process as all other PRs (see [CONTRIBUTING.md](CONTRIBUTING.md)), with the following additional considerations:
185+
186+
### Additional Review Focus Areas
187+
188+
- **Test quality** — AI-generated tests may appear comprehensive but miss edge cases, test only happy paths, or contain incorrect assertions. Review assertions carefully.
189+
- **Hallucinated APIs** — AI may reference methods, classes, or modules that do not exist in this project. Verify all API references against the actual codebase.
190+
- **Naming conventions** — AI-generated names may not match project conventions (e.g., `DataVersion` vs. `Version`, `TypeReference` vs. `TypeRef`). Enforce consistency.
191+
- **Thread safety** — Verify that AI-generated code maintains the project's immutability and thread-safety invariants.
192+
- **Dependency additions** — AI may suggest adding external libraries. Verify necessity and license compatibility.
193+
- **Subtle logic errors** — AI-generated code can appear correct at first glance while containing subtle bugs. Review logic paths carefully.
194+
195+
### Human Review Requirement
196+
197+
- At least **one human maintainer** must review and approve every PR — no exceptions.
198+
- Reviewers may request the contributor to **explain** any AI-generated code.
199+
- Reviewers are not expected to detect undisclosed AI usage. The disclosure responsibility lies with the contributor.
200+
201+
---
202+
203+
## 🛡️ Maintainer Guidelines
204+
205+
Maintainers are held to the **same disclosure and quality standards** as contributors, plus the following additional responsibilities:
206+
207+
### AI Agent PRs
208+
209+
When reviewing and merging AI agent PRs (e.g., from `copilot-swe-agent[bot]`):
210+
211+
- 🔍 Review the **actual code changes**, not just the bot's summary
212+
- 🧪 Run tests **locally** if the changes touch core logic
213+
- ✅ Verify the PR addresses the **linked issue** correctly
214+
- ⚠️ Pay extra attention to changes in security-sensitive or public API areas
215+
216+
### Configuration and Standards
217+
218+
- AI agent configurations (e.g., `CLAUDE.md`, Copilot workspace settings) must **not** bypass project standards such as tests, Checkstyle, or review requirements.
219+
- New AI agents must receive **maintainer consensus** before being added to the `.github/dco.yml` bot exemption list.
220+
- Do not use AI tools to **rubber-stamp** reviews. Every approval must reflect genuine human assessment of the code.
221+
222+
---
223+
224+
## ⚖️ Intellectual Property & Licensing
225+
226+
All contributions — whether human-written or AI-assisted — must be compatible with the project's [MIT License](LICENSE).
227+
228+
### DCO and AI
229+
230+
By submitting AI-assisted code and signing off with the [Developer Certificate of Origin](DCO), you certify that:
231+
232+
1. You have the **right to submit** the work under the MIT License.
233+
2. The AI-generated content does not, to the best of your knowledge, **infringe on third-party copyrights** or include code from proprietary or incompatibly licensed sources.
234+
235+
### Provenance Guidelines
236+
237+
- ⚠️ Avoid using AI tools configured to train on or reproduce code from repositories with **incompatible licenses** (e.g., GPL, AGPL) when generating contributions to this project.
238+
- When in doubt about the **provenance** of AI-generated code, err on the side of rewriting the contribution by hand.
239+
- The human contributor is listed as the **author**; the AI tool is acknowledged via `Co-Authored-By`.
240+
241+
---
242+
243+
## 🔒 Accountability
244+
245+
### Responsibility
246+
247+
- The **human contributor** who submits AI-assisted work is **fully responsible** for it — including bugs, security vulnerabilities, test failures, and convention violations.
248+
- For **AI agent PRs** (where no human is the commit author), the maintainer who requested the agent's work and/or merged the PR assumes responsibility.
249+
- "The AI generated it" is **not** a mitigating factor for quality issues or policy violations.
250+
251+
### Enforcement
252+
253+
- Violations of this policy — particularly **undisclosed AI usage** or **submitting unreviewed AI output** — will be handled constructively on a case-by-case basis.
254+
- Repeated or intentional violations may be escalated through the project's [Code of Conduct](CODE_OF_CONDUCT.md) enforcement process.
255+
- Serious violations (e.g., knowingly submitting AI-generated code with license conflicts) may result in **contribution restrictions**.
256+
257+
---
258+
259+
## 📝 Updates to This Policy
260+
261+
This policy is a **living document**. As AI tools and practices evolve, so will these guidelines.
262+
263+
- Significant changes will be proposed via a **Pull Request** and discussed before merging.
264+
- Contributors are encouraged to suggest improvements by opening an **Issue** or **Discussion**.
265+
- Minor clarifications may be made directly by maintainers.
266+
267+
**Last updated:** March 2026
268+
269+
---
270+
271+
Thank you for helping keep **Aether Datafixers** transparent, secure, and high-quality. 🚀

0 commit comments

Comments
 (0)