This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory.git
The following commit(s) were added to refs/heads/main by this push:
new 28694d1f7 docs: add ai-review policy (#3545)
28694d1f7 is described below
commit 28694d1f7d8b5da8930f85d9c6f2a26a3465d4c2
Author: Shawn Yang <[email protected]>
AuthorDate: Thu Apr 9 11:42:26 2026 +0800
docs: add ai-review policy (#3545)
## Why?
Clarify the project policy for substantial AI-assisted contributions so
contributors complete their own review and verification work before
requesting maintainer review. This keeps accountability with the
contributor and makes the required AI disclosure and review evidence
explicit in the PR workflow.
## What does this PR do?
- Adds an AI review rationale section to `AI_POLICY.md` explaining why
substantial AI-assisted PRs require contributor-led review rather than
shifting that burden to maintainers.
- Requires a documented AI review loop for substantial AI assistance:
contributor self-review first, then two fresh AI reviewers on the
current PR state, one using `.claude/skills/fory-code-review/SKILL.md`
and one without that skill.
- Extends the AI disclosure template and contributor checklist with
`ai_review` and `ai_review_artifacts` requirements, including final
clean review evidence and screenshots from both reviewers.
- Clarifies review-loop terms such as fresh review sessions, final clean
review results, and the expectation that the evidence matches the
current PR diff or current `HEAD`.
- Updates `CONTRIBUTING.md` and the PR template so contributors see the
same AI review requirements when opening a PR.
## Related issues
## AI Contribution Checklist
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
## Does this PR introduce any user-facing change?
This PR changes contributor policy and PR workflow guidance for
AI-assisted submissions. It does not change public APIs or binary
protocol behavior.
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
.github/pull_request_template.md | 3 ++-
AI_POLICY.md | 36 ++++++++++++++++++++++++++++++++++++
CONTRIBUTING.md | 1 +
3 files changed, 39 insertions(+), 1 deletion(-)
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 0440d84ac..797a72ca6 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -35,8 +35,9 @@
https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-fo
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
+- [ ] If `yes`, my PR description includes the required `ai_review` summary
and screenshot evidence of the final clean AI review results from both fresh
reviewers on the current PR diff or current HEAD after the latest code changes.
-<!-- If substantial AI assistance = `yes`, paste the completed checklist and
disclosure block here. -->
+<!-- If substantial AI assistance = `yes`, paste the completed checklist and
disclosure block here, including the final ai_review summary and screenshot
evidence from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes. -->
## Does this PR introduce any user-facing change?
diff --git a/AI_POLICY.md b/AI_POLICY.md
index b80618b23..850189799 100644
--- a/AI_POLICY.md
+++ b/AI_POLICY.md
@@ -12,8 +12,16 @@ The key words MUST, MUST NOT, REQUIRED, SHOULD, and MAY are
interpreted as descr
- The human submitter is responsible for correctness, safety, performance, and
maintainability of all submitted changes.
- License/provenance confirmation: contributors MUST confirm submitted
material is legally compatible and traceable, and MUST comply with [ASF
Generative Tooling
Guidance](https://www.apache.org/legal/generative-tooling.html).
- AI-assisted code MUST be reviewed carefully by the contributor line by line
before submission.
+- For substantial AI assistance, contributors MUST complete the required AI
review loop in Section 5 before opening or updating the PR for maintainer
review.
- Contributors MUST be able to explain and defend design and implementation
details during review.
+### Why AI Review Is Required
+
+- AI-generated code can appear plausible while still containing correctness,
protocol, performance, maintainability, or licensing problems.
+- When AI materially contributes technical content, the contributor's main
responsibility shifts toward rigorous review, correction, and validation, not
just drafting.
+- If contributors skip that review work, the effective burden is transferred
to maintainers, which is not an acceptable review model for this project.
+- The required AI review loop exists to make contributors complete that review
and correction work before requesting maintainer time.
+
## 2. Disclosure (Privacy-Safe)
For substantial AI assistance, PR descriptions MUST include a short `AI Usage
Disclosure` section.
@@ -35,6 +43,8 @@ Required disclosure fields:
- Whether substantial AI assistance was used (`yes` or `no`)
- Scope of assistance (for example: design drafting, code drafting, refactor
suggestions, tests, docs)
- Affected files or subsystems (high-level)
+- AI review summary (self-review completed, AI review loop status, and final
result)
+- Final AI review artifacts (embedded screenshots or links showing the final
clean AI review results from both fresh reviewers on the current PR diff or
current HEAD after the latest code changes)
- Human verification performed (checks run locally or in CI, and results
reviewed by the contributor)
- Provenance and license confirmation (see Section 6)
@@ -45,6 +55,8 @@ AI Usage Disclosure
- substantial_ai_assistance: yes
- scope: <design drafting | code drafting | refactor suggestions | tests |
docs | other>
- affected_files_or_subsystems: <high-level paths/modules>
+- ai_review: <line-by-line self-review completed; summarize the two-reviewer
loop and final no-further-comments result>
+- ai_review_artifacts: <embedded screenshots or links showing the final clean
review results from both fresh reviewers on the current PR diff or current HEAD
after the latest code changes>
- human_verification: <checks run locally or in CI + pass/fail summary +
contributor reviewed results>
- performance_verification: <N/A or benchmark/regression evidence summary>
- provenance_license_confirmation: <Apache-2.0-compatible provenance
confirmed; no incompatible third-party code introduced>
@@ -76,6 +88,22 @@ For AI-assisted non-trivial work without prior alignment,
maintainers MAY reques
Every AI-assisted PR MUST provide verifiable evidence of local or CI
validation:
+For substantial AI assistance, every PR MUST also provide verifiable evidence
of a completed AI review loop before maintainer review:
+
+- The contributor personally performs a line-by-line self-review first and
fixes all issues found before requesting AI review.
+- The contributor then runs two fresh AI review agents on the current PR diff
or current HEAD after the latest code changes:
+ - one reviewer MUST use `.claude/skills/fory-code-review/SKILL.md`
+ - one reviewer MUST NOT use that skill
+- The contributor addresses all actionable comments from both reviewers,
reruns both reviewers on the updated diff, and repeats this loop until both
reviewers report no further actionable comments.
+- The PR body MUST include the final clean AI review result from both
reviewers plus screenshot evidence in the `AI Usage Disclosure`.
+- If the contributor cannot produce this evidence, the PR is not ready for
maintainer review.
+
+Definitions for AI review evidence:
+
+- Fresh AI review agent means a new clean-context review session started on
the current diff after the latest code changes. Reusing an old reviewer thread
as the final review evidence is not sufficient.
+- Final clean AI review result means the last rerun of both reviewers on the
current PR diff or current HEAD, with no unresolved actionable comments
remaining.
+- Screenshot evidence must show, for each reviewer, the reviewer identity or
workflow label, the reviewed diff/commit or PR state, and the clean
no-further-actionable-comments result. Persisted links with equivalent
information MAY be used when screenshots are impractical.
+
Definition of adequate human verification:
- The contributor personally runs the relevant checks locally or in project CI
and reviews the results.
@@ -122,6 +150,7 @@ Maintainers MAY close or return PRs that materially fail
project standards, incl
- Contributor cannot explain key implementation logic
- Missing required disclosure for substantial AI assistance
+- Missing required AI review loop evidence, final clean reviewer outputs, or
screenshot artifacts in the PR body
- Missing or inadequate human verification evidence for changed behavior
- Redundant implementation of existing utilities without clear necessity
- Introduction of dead code, unused helpers, or placeholder abstractions
without justification
@@ -140,6 +169,7 @@ Before merge, maintainers MAY request:
- Rework of sections that do not meet standards
Maintainers MAY close PRs that remain non-compliant after feedback.
+For substantial AI-assisted PRs that omit the required final AI review
evidence, maintainers MAY close the PR directly without performing review on
the contributor's behalf.
Any long-term contribution restrictions MUST follow Apache project governance
and community process, and SHOULD be documented with clear rationale.
@@ -151,6 +181,10 @@ This is the canonical checklist for the PR template AI
section.
- [ ] If `yes`, I included the standardized `AI Usage Disclosure` block below.
- [ ] If `yes`, I can explain and defend all important changes without AI help.
- [ ] If `yes`, I reviewed AI-assisted code changes line by line before
submission.
+- [ ] If `yes`, I completed line-by-line self-review first and fixed issues
before requesting AI review.
+- [ ] If `yes`, I ran two fresh AI review agents on the current PR diff or
current HEAD after the latest code changes: one using
`.claude/skills/fory-code-review/SKILL.md` and one without that skill.
+- [ ] If `yes`, I addressed all AI review comments and repeated the review
loop until both ai reviewers reported no further actionable comments.
+- [ ] If `yes`, I attached screenshot evidence of the final clean AI review
results from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes in this PR body.
- [ ] If `yes`, I ran adequate human verification and recorded evidence
(checks run locally or in CI, pass/fail summary, and confirmation I reviewed
results).
- [ ] If `yes`, I added/updated tests and specs where required.
- [ ] If `yes`, I validated protocol/performance impacts with evidence when
applicable.
@@ -163,6 +197,8 @@ AI Usage Disclosure
- substantial_ai_assistance: yes
- scope: <design drafting | code drafting | refactor suggestions | tests |
docs | other>
- affected_files_or_subsystems: <high-level paths/modules>
+- ai_review: <line-by-line self-review completed; summarize the two-reviewer
loop and final no-further-comments result>
+- ai_review_artifacts: <embedded screenshots or links showing the final clean
review results from both fresh reviewers on the current PR diff or current HEAD
after the latest code changes>
- human_verification: <checks run locally or in CI + pass/fail summary +
contributor reviewed results>
- performance_verification: <N/A or benchmark/regression evidence summary>
- provenance_license_confirmation: <Apache-2.0-compatible provenance
confirmed; no incompatible third-party code introduced>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3d9ee2550..dd49508c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,6 +33,7 @@ Key points:
- AI tools are allowed as assistants, but contributors remain fully
responsible for all submitted changes.
- AI-assisted code must be reviewed carefully line by line before submission,
and contributors must be able to explain and defend it during review.
+- For substantial AI assistance, contributors must complete a self-review
first, then repeat a two-reviewer AI review loop until both reviewers report no
further actionable comments, and include the final clean review screenshots in
the PR disclosure.
- For substantial AI assistance, provide privacy-safe disclosure in the PR
using the [AI Contribution
Checklist](./AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
template. Minor/narrow AI assistance does not require full disclosure.
- Include adequate human verification evidence (for example exact
build/lint/test commands and pass/fail outcomes), and add/update tests and
specs where required.
- For protocol/type-mapping/wire-format or performance-sensitive changes,
provide the required compatibility/performance validation evidence.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
