docs: simplify PR AI checklist and rename AI policy file (#3470)

chaokunyang · web-flow · commit 7f44cfa853ee · 2026-03-11T16:35:20.000+05:30
## Why?



## What does this PR do?



## Related issues



## AI Contribution Checklist (required when AI assistance = `yes`)




- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] 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 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.
- [ ] If `yes`, I verified licensing and provenance compliance.

AI Usage Disclosure (only when substantial AI assistance = `yes`):



```text
AI Usage Disclosure
- substantial_ai_assistance: yes
- scope: &lt;design drafting | code drafting | refactor suggestions | tests | docs | other&gt;
- affected_files_or_subsystems: &lt;high-level paths/modules&gt;
- human_verification: &lt;checks run locally or in CI + pass/fail summary + contributor reviewed results&gt;
- performance_verification: &lt;N/A or benchmark/regression evidence summary&gt;
- provenance_license_confirmation: &lt;Apache-2.0-compatible provenance confirmed; no incompatible third-party code introduced&gt;
```

## Does this PR introduce any user-facing change?



- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?

## Benchmark
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -28,35 +28,15 @@ Is there any related issue? If this PR closes them you say say fix/closes:
 - Fixes #xxxx2
 -->
 
-## AI Contribution Checklist (required when AI assistance = `yes`)
+## AI Contribution Checklist
 
-<!-- Please read: https://github.com/apache/fory/blob/main/AI_CONTRIBUTION_POLICY.md -->
-<!-- Mark `yes` when AI materially influenced technical content.
-Examples: non-trivial code/test logic generated by AI (even one function), about 20+ added/changed lines influenced by AI, or AI influence on API/protocol/performance/architecture decisions.
-Mark `no` for minor/narrow assistance only (spelling/grammar/formatting/trivial comment or wording edits with no behavior impact). -->
+<!-- Full requirements and disclosure template:
+https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs -->
 
 - [ ] Substantial AI assistance was used in this PR: `yes` / `no`
-- [ ] 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 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.
-- [ ] If `yes`, I verified licensing and provenance compliance.
-
-AI Usage Disclosure (only when substantial AI assistance = `yes`):
-
-<!-- Use this standard template to keep reviews consistent and low-overhead. -->
-
-```text
-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>
-- 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>
-```
+- [ ] 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 substantial AI assistance = `yes`, paste the completed checklist and disclosure block here. -->
 
 ## Does this PR introduce any user-facing change?
 
diff --git a/AI_POLICY.md b/AI_POLICY.md
@@ -18,6 +18,7 @@ The key words MUST, MUST NOT, REQUIRED, SHOULD, and MAY are interpreted as descr
 
 For substantial AI assistance, PR descriptions MUST include a short `AI Usage Disclosure` section.
 For minor or narrow AI assistance, full disclosure is not required.
+The PR template keeps this section intentionally short and links to Section 9 for the complete checklist.
 
 Definition of substantial AI assistance:
 
@@ -144,13 +145,28 @@ Any long-term contribution restrictions MUST follow Apache project governance an
 
 ## 9. Contributor Checklist (for AI-Assisted PRs)
 
-- [ ] I can explain and defend all important changes.
-- [ ] I reviewed AI-assisted code line by line before submission.
-- [ ] I provided `AI Usage Disclosure` without exposing private/internal details.
-- [ ] I ran relevant local build/lint/test checks and reported outcomes.
-- [ ] I added/updated tests and specs where required.
-- [ ] I validated protocol/performance impacts with evidence when applicable.
-- [ ] I verified licensing and provenance compliance.
+This is the canonical checklist for the PR template AI section.
+
+- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
+- [ ] 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 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.
+- [ ] If `yes`, I verified licensing and provenance compliance.
+
+AI Usage Disclosure (only when substantial AI assistance = `yes`):
+
+```text
+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>
+- 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>
+```
 
 ## 10. Governance Note
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,13 +27,13 @@ For more details, please check [pr-lint.yml](./.github/workflows/pr-lint.yml).
 
 ## AI-assisted contributions
 
-For full requirements, see [AI Contribution Policy](./AI_CONTRIBUTION_POLICY.md).
+For full requirements, see [AI Contribution Policy](./AI_POLICY.md).
 
 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, provide privacy-safe disclosure in the PR using the standard template in `.github/pull_request_template.md`. Minor/narrow AI assistance does not require full 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.
 - Ensure licensing and provenance compliance with [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) and do not submit content with uncertain provenance.
