diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c02c4e5..4312cf1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -24,8 +24,15 @@ Closes #… ## Breaking Changes Describe any breaking changes or migration steps. +## AI Disclosure +- [ ] This PR includes AI-generated or AI-assisted content +- If checked, describe which parts and which AI tool was used: … + +See [AI Usage Guidelines](../../AI_USAGE.md) for details. + ## Checklist - [ ] Code follows project conventions - [ ] Public APIs are documented - [ ] Tests cover new behavior - [ ] No unnecessary dependencies added +- [ ] AI usage disclosed (if applicable) diff --git a/.github/workflows/retarget-pr-to-develop.yml b/.github/workflows/retarget-pr-to-develop.yml new file mode 100644 index 0000000..1dc79c0 --- /dev/null +++ b/.github/workflows/retarget-pr-to-develop.yml @@ -0,0 +1,41 @@ +name: Retarget PRs from main to develop + +on: + pull_request: + types: [opened] + branches: [main] + +permissions: + contents: read + pull-requests: write + +jobs: + retarget: + runs-on: ubuntu-latest + if: ${{ !startsWith(github.head_ref, 'release/') }} + steps: + - name: Retarget PR to develop + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + echo "::notice::PR #${{ github.event.pull_request.number }} targets main from '${{ github.head_ref }}' β€” retargeting to develop." + gh pr edit ${{ github.event.pull_request.number }} \ + --repo ${{ github.repository }} \ + --base develop + + - name: Leave a comment explaining the retarget + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh pr comment ${{ github.event.pull_request.number }} \ + --repo ${{ github.repository }} \ + --body "$(cat <<'EOF' + πŸ”€ **This PR has been automatically retargeted from `main` to `develop`.** + + In this project, `develop` is the integration branch for all feature and fix contributions. Only `release/*` branches may target `main` directly. + + If this retarget was a mistake (e.g., you intended to create a release PR), please update the base branch manually. + + See [CONTRIBUTING.md](../blob/develop/CONTRIBUTING.md) for details on our branching strategy. + EOF + )" diff --git a/AI_USAGE.md b/AI_USAGE.md new file mode 100644 index 0000000..ce4c53c --- /dev/null +++ b/AI_USAGE.md @@ -0,0 +1,271 @@ +# πŸ€– AI Usage Guidelines + +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. + +--- + +## πŸ“‹ Purpose & Scope + +### Why This Policy Exists + +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**. + +### Who This Applies To + +- βœ… All **contributors** (external and internal) submitting code, documentation, or other content +- βœ… All **maintainers** reviewing, merging, or creating contributions +- βœ… **Automated AI agents** (e.g., `copilot-swe-agent[bot]`) that submit PRs directly + +### What This Covers + +This policy applies to all forms of contribution: + +- Source code and tests +- Documentation and Javadoc +- Commit messages and PR descriptions +- Issue comments and discussion posts +- Code reviews and review comments +- Configuration and CI/CD changes + +--- + +## βš–οΈ General Principles + +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. +2. **Same quality bar β€” no exceptions.** AI-generated output must meet the exact same standards as human-written code: conventions, tests, documentation, and review. +3. **Transparency is mandatory.** Disclosure of significant AI assistance is required, not optional. Honest disclosure is always better than concealment. +4. **Quality and security over speed.** AI can accelerate development, but speed must never come at the expense of correctness, maintainability, or security. +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. + +--- + +## βœ… Permitted Uses + +AI tools may be used in the following areas, subject to the conditions listed: + +| Use Case | Status | Conditions | +|---------------------------------------|-----------|-------------------------------------------------------------------| +| Code generation (features, bug fixes) | βœ… Allowed | Must be fully understood, tested, and reviewed by the contributor | +| Test generation (JUnit 5 / AssertJ) | βœ… Allowed | Assertions and edge cases must be manually verified | +| Documentation and Javadoc | βœ… Allowed | Must be factually accurate β€” AI may hallucinate API details | +| Boilerplate and scaffolding | βœ… Allowed | Still requires review for project conventions | +| Commit message drafting | βœ… Allowed | Must accurately describe the actual changes | +| PR description drafting | βœ… Allowed | Must reflect the real changes, not AI assumptions | +| Refactoring suggestions | βœ… Allowed | All existing tests must pass; behavior must be preserved | +| Issue triage and response drafting | βœ… Allowed | Must be reviewed before posting | + +**Important:** All permitted uses require [disclosure](#-disclosure-requirements) and are subject to [quality standards](#-quality-standards). + +--- + +## 🚫 Restricted & Prohibited Uses + +### 🏷️ Good First Issues β€” Learning First + +Issues labeled **`good first issue`** are **strongly encouraged** to be completed **primarily without significant AI assistance**. + +**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. + +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. + +> Contributors may still use AI for small suggestions or learning purposes, but the core solution should reflect personal understanding and effort. + +### ⚠️ Restricted Uses + +The following areas require **extra scrutiny and maintainer approval** before AI-assisted contributions are accepted: + +- **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). +- **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. +- **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. +- **CI/CD pipeline modifications** β€” Changes to GitHub Actions workflows, Maven profiles, or build configuration require maintainer review for security and correctness. + +### 🚫 Prohibited Uses + +The following uses of AI are **not permitted**: + +- **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. +- **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. +- **Undisclosed significant AI usage** β€” Knowingly concealing significant AI assistance violates this policy. See [Accountability](#-accountability). +- **AI-generated vulnerability reports** β€” Automated AI scanning to generate public vulnerability reports is prohibited. Follow the private disclosure process in [SECURITY.md](SECURITY.md). +- **Bypassing project standards** β€” Using AI to circumvent tests, Checkstyle rules, or other quality gates is prohibited. +- **AI for license or legal decisions** β€” AI tools must not be relied upon for license compatibility analysis, DCO compliance interpretation, or other legal matters. + +--- + +## πŸ“’ Disclosure Requirements + +Disclosure of AI assistance is **mandatory**. This is the most important operational requirement of this policy. + +### πŸ”Ž When to Disclose + +Disclosure is required whenever AI tools were used to **generate or substantially modify** code, documentation, or other contributions. + +**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. + +**Exempt:** Minor AI-assisted tasks such as IDE autocomplete suggestions, spell-checking, or grammar corrections do not require disclosure. + +### πŸ’¬ In Commits + +Use a `Co-Authored-By` trailer in your commit message: + +``` +feat: Add field renaming support for nested types + +Implemented recursive field renaming in NestedTypeFix with +full test coverage. + +Co-Authored-By: GitHub Copilot +Signed-off-by: Your Name +``` + +Common AI tool trailers: + +``` +Co-Authored-By: GitHub Copilot +Co-Authored-By: Claude +Co-Authored-By: ChatGPT +``` + +For automated AI agents (e.g., `copilot-swe-agent[bot]`), the commit author field already serves as disclosure. + +### πŸ“ In Pull Requests + +1. Check the **AI Disclosure** checkbox in the [PR template](.github/PULL_REQUEST_TEMPLATE.md). +2. In the PR description, state **which parts** were AI-assisted and **which tool** was used. + +Example: + +```markdown +**AI Disclosure:** The implementation in `NestedTypeFix.java` and its unit tests +were generated with Claude and reviewed/modified by the contributor. The Javadoc +was written manually. +``` + +### πŸ’­ In Issues and Discussions + +When posting AI-generated analysis, suggestions, or responses, add a brief note: + +> *This response was drafted with AI assistance.* + +--- + +## πŸ” Quality Standards + +### Code Quality + +AI-generated code must meet the same standards as human-written code: + +- βœ… Pass all existing tests (`mvn clean package`) +- βœ… Include new tests for new behavior (JUnit 5 + AssertJ) +- βœ… Follow project coding conventions (validated by Checkstyle) +- βœ… Include proper Javadoc for all public API methods +- βœ… Use JetBrains annotations (`@NotNull`, `@Nullable`) where appropriate +- βœ… Use Guava `Preconditions` for argument validation +- βœ… Maintain thread-safety invariants β€” Aether Datafixers types are immutable and thread-safe by design +- βœ… Not introduce unnecessary dependencies + +### Documentation Quality + +AI-generated documentation must: + +- βœ… Be **factually accurate** β€” AI tools frequently hallucinate API details, method signatures, and module names +- βœ… Be **consistent** with existing documentation style and structure +- βœ… Reference **correct** class, method, and module names +- βœ… Not contradict existing documentation + +### Understanding Requirement + +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. + +--- + +## πŸ”Ž Review Process + +AI-assisted PRs follow the same review process as all other PRs (see [CONTRIBUTING.md](CONTRIBUTING.md)), with the following additional considerations: + +### Additional Review Focus Areas + +- **Test quality** β€” AI-generated tests may appear comprehensive but miss edge cases, test only happy paths, or contain incorrect assertions. Review assertions carefully. +- **Hallucinated APIs** β€” AI may reference methods, classes, or modules that do not exist in this project. Verify all API references against the actual codebase. +- **Naming conventions** β€” AI-generated names may not match project conventions (e.g., `DataVersion` vs. `Version`, `TypeReference` vs. `TypeRef`). Enforce consistency. +- **Thread safety** β€” Verify that AI-generated code maintains the project's immutability and thread-safety invariants. +- **Dependency additions** β€” AI may suggest adding external libraries. Verify necessity and license compatibility. +- **Subtle logic errors** β€” AI-generated code can appear correct at first glance while containing subtle bugs. Review logic paths carefully. + +### Human Review Requirement + +- At least **one human maintainer** must review and approve every PR β€” no exceptions. +- Reviewers may request the contributor to **explain** any AI-generated code. +- Reviewers are not expected to detect undisclosed AI usage. The disclosure responsibility lies with the contributor. + +--- + +## πŸ›‘οΈ Maintainer Guidelines + +Maintainers are held to the **same disclosure and quality standards** as contributors, plus the following additional responsibilities: + +### AI Agent PRs + +When reviewing and merging AI agent PRs (e.g., from `copilot-swe-agent[bot]`): + +- πŸ” Review the **actual code changes**, not just the bot's summary +- πŸ§ͺ Run tests **locally** if the changes touch core logic +- βœ… Verify the PR addresses the **linked issue** correctly +- ⚠️ Pay extra attention to changes in security-sensitive or public API areas + +### Configuration and Standards + +- AI agent configurations (e.g., `CLAUDE.md`, Copilot workspace settings) must **not** bypass project standards such as tests, Checkstyle, or review requirements. +- New AI agents must receive **maintainer consensus** before being added to the `.github/dco.yml` bot exemption list. +- Do not use AI tools to **rubber-stamp** reviews. Every approval must reflect genuine human assessment of the code. + +--- + +## βš–οΈ Intellectual Property & Licensing + +All contributions β€” whether human-written or AI-assisted β€” must be compatible with the project's [MIT License](LICENSE). + +### DCO and AI + +By submitting AI-assisted code and signing off with the [Developer Certificate of Origin](DCO), you certify that: + +1. You have the **right to submit** the work under the MIT License. +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. + +### Provenance Guidelines + +- ⚠️ 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. +- When in doubt about the **provenance** of AI-generated code, err on the side of rewriting the contribution by hand. +- The human contributor is listed as the **author**; the AI tool is acknowledged via `Co-Authored-By`. + +--- + +## πŸ”’ Accountability + +### Responsibility + +- The **human contributor** who submits AI-assisted work is **fully responsible** for it β€” including bugs, security vulnerabilities, test failures, and convention violations. +- 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. +- "The AI generated it" is **not** a mitigating factor for quality issues or policy violations. + +### Enforcement + +- Violations of this policy β€” particularly **undisclosed AI usage** or **submitting unreviewed AI output** β€” will be handled constructively on a case-by-case basis. +- Repeated or intentional violations may be escalated through the project's [Code of Conduct](CODE_OF_CONDUCT.md) enforcement process. +- Serious violations (e.g., knowingly submitting AI-generated code with license conflicts) may result in **contribution restrictions**. + +--- + +## πŸ“ Updates to This Policy + +This policy is a **living document**. As AI tools and practices evolve, so will these guidelines. + +- Significant changes will be proposed via a **Pull Request** and discussed before merging. +- Contributors are encouraged to suggest improvements by opening an **Issue** or **Discussion**. +- Minor clarifications may be made directly by maintainers. + +**Last updated:** March 2026 + +--- + +Thank you for helping keep **Aether Datafixers** transparent, secure, and high-quality. πŸš€ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99e448b..f6b99b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,43 @@ We welcome all contributions, whether it's fixing bugs, adding features, improvi --- +## 🌿 Branching Strategy + +This project follows a **Git Flow**-inspired branching model with two long-lived branches and several short-lived branch types. + +### Long-Lived Branches + +| Branch | Purpose | +|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `main` | πŸ”’ **Production-ready code only.** Represents the latest stable release. Direct commits and PRs from feature/fix branches are **not allowed** β€” only `release/*` branches may be merged into `main`. | +| `develop` | πŸ”§ **Integration branch.** All feature and fix contributions are merged here. This is the **default target** for your PRs. | + +### Short-Lived Branches + +| Branch Pattern | Base Branch | Merges Into | Purpose | +|----------------|-------------|--------------------|-----------------------------------------------------------------------------------------------------| +| `feature/*` | `develop` | `develop` | New features (e.g., `feature/cli-module`, `feature/migration-diagnostics`) | +| `bugfix/*` | `develop` | `develop` | Bug fixes (e.g., `bugfix/javadoc-site-compiling-fixes`) | +| `release/*` | `develop` | `main` + `develop` | Release preparation (e.g., `release/0.5.x`). The **only** branch type allowed to merge into `main`. | +| `hotfix/*` | `main` | `main` + `develop` | Critical production fixes that cannot wait for the next release cycle. | + +### Branch Flow Diagram + +``` +feature/* ──→ develop ──→ release/* ──→ main +bugfix/* ──→ develop ──↗ ↑ + hotfix/* +``` + +### ⚠️ Important Rules + +- **Never target `main` with feature or bugfix PRs.** PRs that accidentally target `main` are [automatically retargeted to `develop`](.github/workflows/retarget-pr-to-develop.yml). PRs from non-`release/*` branches to `main` are [blocked](.github/workflows/block-main-non-release.yml). +- **Always branch off `develop`** for features and bug fixes. +- **Keep branches short-lived.** Merge early and often to avoid painful conflicts. +- **Delete branches after merging.** Stale branches clutter the repository. + +--- + ## πŸš€ How to Contribute ### 1️⃣ Fork the Repository @@ -17,10 +54,18 @@ cd aether-datafixers ``` ### 2️⃣ Create a Branch + +Branch off `develop` and use the correct prefix: + ```sh +git checkout develop +git pull origin develop git checkout -b feature/new-awesome-feature ``` -Use a meaningful branch name (e.g., `fix/builder-bug` or `feature/optic-integration`). + +Use a meaningful branch name with the appropriate prefix: +- `feature/` β€” for new features (e.g., `feature/optic-integration`) +- `bugfix/` β€” for bug fixes (e.g., `bugfix/builder-null-pointer`) ### 3️⃣ Implement Your Changes - Follow the coding style of the project. @@ -30,15 +75,16 @@ Use a meaningful branch name (e.g., `fix/builder-bug` or `feature/optic-integrat ### 4️⃣ Commit and Push ```sh git add . -git commit -m "Added new awesome feature" +git commit -s -m "Add new awesome feature" git push origin feature/new-awesome-feature ``` ### 5️⃣ Open a Pull Request (PR) 1. Go to the **Pull Requests** tab in the repository. 2. Click **New Pull Request**. -3. Select your branch and describe your changes. -4. Wait for a review and feedback! +3. Set the **base branch** to `develop` (not `main`!). +4. Describe your changes and fill out the PR template. +5. Wait for a review and feedback! --- @@ -67,4 +113,10 @@ git commit -s -m "Your commit message" This adds a `Signed-off-by: Your Name ` line to your commit, confirming that you agree to the DCO. +## πŸ€– AI-Assisted Contributions + +We allow AI-assisted contributions under strict conditions. If you use AI tools (GitHub Copilot, Claude, ChatGPT, etc.), you **must** follow our [AI Usage Guidelines](AI_USAGE.md) β€” including mandatory disclosure and quality standards. + +--- + πŸš€ **Happy Coding!** diff --git a/README.md b/README.md index 57eaaf9..f994502 100644 --- a/README.md +++ b/README.md @@ -546,7 +546,7 @@ java -jar aether-datafixers-benchmarks/target/benchmarks.jar We welcome contributions of all kinds β€” bug fixes, features, documentation improvements, and discussions. -Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a pull request. This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). +Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a pull request. This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). For AI-assisted contributions, please review our [AI Usage Guidelines](AI_USAGE.md). ## πŸ”’ Security