You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/04/09 03:42:31 UTC
(fory) branch main updated: docs: add ai-review policy (#3545)
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 <sh...@gmail.com>
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: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org