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 6abb916c7 docs: add ai contributing policy (#3437)
6abb916c7 is described below
commit 6abb916c7651e7d1075a4363c0a41f1b079c2ad7
Author: Shawn Yang <[email protected]>
AuthorDate: Wed Mar 11 12:15:09 2026 +0800
docs: add ai contributing policy (#3437)
## Why?
Apache Fory is aperformance-critical foundational serialization
framework.
As AI-assisted contributions increase, we need a project policy that
keeps review quality high, protects legal/provenance safety, and
preserves long-term maintainability.
This policy is intended to:
- keep human accountability as the core rule
- reduce low-signal or unverified AI-generated changes
- require verifiable testing/performance evidence for sensitive paths
- align contribution practice with ASF legal and governance expectations
## What does this PR do?
- Adds a new top-level policy document: `AI_CONTRIBUTION_POLICY.md`.
- Defines requirements for AI-assisted contributions, including:
- contributor responsibility and line-by-line self review
- privacy-safe disclosure expectations
- verification requirements (tests/spec/perf evidence where applicable)
- licensing/provenance requirements
- quality gate and maintainer enforcement process
- Updates `.github/pull_request_template.md` to add an AI contribution
checklist for PR authors.
## Related issues
N/A
## 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
N/A (documentation and PR template change only)
---
.github/pull_request_template.md | 30 ++++++++
AI_CONTRIBUTION_POLICY.md | 158 +++++++++++++++++++++++++++++++++++++++
CONTRIBUTING.md | 13 ++++
3 files changed, 201 insertions(+)
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 950f23dd1..fda63ff01 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -28,6 +28,36 @@ 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`)
+
+<!-- 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). -->
+
+- [ ] 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>
+```
+
## Does this PR introduce any user-facing change?
<!--
diff --git a/AI_CONTRIBUTION_POLICY.md b/AI_CONTRIBUTION_POLICY.md
new file mode 100644
index 000000000..32352f7b1
--- /dev/null
+++ b/AI_CONTRIBUTION_POLICY.md
@@ -0,0 +1,158 @@
+# AI Contribution Policy
+
+Apache Fory is a performance-critical foundational serialization framework
with cross-language compatibility requirements.
+AI tools are welcome as assistants, but project quality, legal safety, and
maintainability standards are unchanged.
+
+The key words MUST, MUST NOT, REQUIRED, SHOULD, and MAY are interpreted as
described in RFC 2119.
+
+## 1. Core Principle
+
+- AI tools MAY assist contribution work.
+- AI tools MUST NOT replace contributor accountability.
+- 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.
+- Contributors MUST be able to explain and defend design and implementation
details during review.
+
+## 2. Disclosure (Privacy-Safe)
+
+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.
+
+Definition of substantial AI assistance:
+
+- Substantial means AI materially influenced technical content, not only
writing style.
+- Contributors MUST mark AI assistance as substantial (`yes`) if any of the
following apply:
+ - AI generated or rewrote non-trivial code/test logic (even for a small
change or a single function).
+ - AI-generated or AI-refactored content is about 20 or more added/changed
lines in aggregate.
+ - AI materially influenced API, protocol, type mapping, performance, memory,
or architecture decisions.
+ - AI produced substantive technical text used in PR rationale (beyond
grammar/translation cleanup).
+- Contributors MAY mark substantial AI assistance as `no` for minor or narrow
assistance only, such as spelling/grammar fixes, formatting, trivial comment
wording edits, or other non-technical edits with no behavior impact.
+
+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)
+- Human verification performed (checks run locally or in CI, and results
reviewed by the contributor)
+- Provenance and license confirmation (see Section 6)
+
+Standard disclosure template (recommended):
+
+```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>
+```
+
+To protect privacy and enterprise security:
+
+- Contributors are NOT required to disclose model names, provider names,
private prompts, or internal workflow details.
+- Maintainers MAY request additional clarification only when necessary for
legal or technical review.
+
+## 3. Human Communication Requirements
+
+The following MUST be human-authored (translation and grammar correction tools
are acceptable):
+
+- Review responses
+- Design rationale and tradeoff discussion
+- Risk analysis and production impact explanation
+
+Generated filler text, evasive responses, or content that does not reflect
contributor understanding may result in PR closure.
+
+## 4. Scope Alignment Before Implementation
+
+For non-trivial changes (especially
architecture/protocol/performance-sensitive work), contributors SHOULD align
scope in an issue or discussion before implementation.
+
+This expectation applies to all contributors, whether AI-assisted or not.
+For AI-assisted non-trivial work without prior alignment, maintainers MAY
request scope alignment before continuing review.
+
+## 5. Verification Requirements
+
+Every AI-assisted PR MUST provide verifiable evidence of local or CI
validation:
+
+Definition of adequate human verification:
+
+- The contributor personally runs the relevant checks locally or in project CI
and reviews the results.
+- Verification includes concrete evidence (exact commands and pass/fail
outcomes), not only claims.
+- Verification covers the changed behavior with targeted tests where
applicable.
+- For protocol or performance-sensitive changes, verification includes the
required compatibility tests and/or benchmark/regression evidence.
+
+- Confirmation that contributor performed line-by-line self-review of
AI-assisted code changes
+- Build/lint/test checks run locally or in CI
+- Targeted tests for changed behavior
+- Results summary (pass/fail and relevant environment context)
+
+Additional REQUIRED checks for Fory-critical paths:
+
+- Protocol, type mapping, or wire-format changes:
+ - Update relevant docs under `docs/specification/**`
+ - Add or update cross-language compatibility tests where applicable
+- Performance-sensitive changes (serialization/deserialization hot paths,
memory allocation behavior, codegen, buffer logic):
+ - Provide benchmark or regression evidence
+ - Justify any measurable performance or allocation impact
+
+Claims without evidence may be treated as incomplete.
+
+## 6. Licensing, Copyright, and Provenance
+
+Contributors MUST follow ASF legal guidance and project licensing policy,
including:
+
+- [ASF Generative Tooling
Guidance](https://www.apache.org/legal/generative-tooling.html)
+- ASF third-party licensing requirements
+- Apache-2.0 compatibility obligations
+
+Contributors MUST ensure:
+
+- No incompatible third-party code is introduced
+- Reused material has compatible licensing and required attribution
+- AI-generated output does not include unauthorized copyrighted fragments
+
+If provenance is uncertain, contributors MUST remove or replace the material
before submission.
+Maintainers MAY request provenance clarification when needed.
+
+## 7. Quality Gate and Non-Acceptance Conditions
+
+Maintainers MAY close or return PRs that materially fail project standards,
including:
+
+- Contributor cannot explain key implementation logic
+- Missing required disclosure for substantial AI assistance
+- 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
+- Protocol or performance claims without reproducible evidence
+- Large unfocused changes with unclear scope or ownership
+
+This is not a ban on AI usage; it is a quality and maintainability gate.
+
+## 8. Review and Enforcement Process
+
+Before merge, maintainers MAY request:
+
+- Additional tests, benchmarks, or spec updates
+- PR split into smaller verifiable commits
+- Clarification of technical rationale, provenance, or licensing
+- Rework of sections that do not meet standards
+
+Maintainers MAY close PRs that remain non-compliant after feedback.
+
+Any long-term contribution restrictions MUST follow Apache project governance
and community process, and SHOULD be documented with clear rationale.
+
+## 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.
+
+## 10. Governance Note
+
+This policy complements, but does not replace, existing ASF and Apache Fory
governance, contribution, and legal policies.
+If conflicts arise, ASF legal and project governance rules take precedence.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 02232ec3e..a519ce5d5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,6 +25,19 @@ please check [Apache Fory™ Java
Benchmark](https://github.com/apache/fory/blob
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).
+
+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.
+- 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.
+
## Testing
For environmental requirements, please check
[DEVELOPMENT.md](./docs/guide/DEVELOPMENT.md).
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
