diff --git a/AGENTS.md b/AGENTS.md index e01f43a97f..ce90f00ec4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,17 @@ This file provides guidance for AI coding agents working with the Apache Fesod (Incubating) codebase. +## AI Policy (read first) + +Before any task, read [AI_POLICY.md](./AI_POLICY.md) and explicitly tell the user you have read it. + +Hard rules for agents: + +- DO NOT open PRs, issues, or post comments on your own. All submissions MUST be manually reviewed and pushed by a human. +- DO NOT write PR descriptions, review comments, or issue reports on your own. You may ONLY translate, proofread, or polish text originally drafted by the human. +- ALWAYS remind the human to read and understand the whole diff. +- ALWAYS list non-trivial unknowns and assumptions so the human can selectively include them in the PR description. + ## Project Overview Apache Fesod (Incubating) is a Java library for processing spreadsheets (XLS/XLSX/CSV) without OOM, derived from Alibaba EasyExcel. It uses Apache POI under the hood with streaming SAX-based reading. The project is an Apache incubator project and must follow ASF conventions. diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 0000000000..95835f1242 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1,53 @@ + + +# AI POLICY + +We welcome contributors using AI as a tool for coding and learning. However, **using tools does not replace human thought and responsibility**. Every contributor remains ultimately responsible for the code and comments they submit. + +A core value of open source is **human collaboration, knowledge sharing, and trust**. Maintainer review capacity is very limited; we cannot accept a dynamic where reviewers become proxies driving or debugging the contributor's AI tool. To ensure project quality and efficient community collaboration, please adhere to the following guidelines: + +--- + +## Pull Request + +- Before submitting a PR, the author must personally read the code, understand the core design end-to-end, and be able to clearly explain their changes during review. Submitting unverified or undigested content is strictly prohibited; even if the code runs, an author who cannot explain its principles is essentially offloading the entire burden of comprehension and verification onto reviewers, and the author gains no growth from the process. +- It is completely normal to not fully understand every detail of AI-generated code. Please proactively call out these unknowns and assumptions in your PR description so reviewers can work with you to address any concerns. +- We strictly prohibit automatic, unattended, bot-owned, or bulk submissions that lack meaningful human review. We require every submission to have a human in the loop who genuinely understands the work produced by AI and takes personal responsibility for it. +- All contributions must strictly comply with the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html). + +--- + +## Communication & Discussion + +Code review is not just about merging code; it is about engaging with **you as a person** (rather than your AI tool) to help you grow and integrate into the community. Whether opening an issue, describing a PR, or answering questions during review, please express yourself in your own words, and never copy-paste unreviewed, AI-generated content directly. + +Unreviewed AI replies place the burden of discernment entirely on the reviewer and deny you the opportunity to learn. Common examples of such unhelpful replies include mechanically summarizing the diff instead of addressing the actual question, listing local commands and checks that CI already covers, or evading design questions with generic descriptions of code changes. + +We fully understand that non-native English speakers may use AI for reading, polishing, or translating comments. Using AI to assist with language is completely acceptable, provided the final text accurately reflects your own voice, ideas, and intent. + +--- + +## AI-Assisted Reviews + +The same standards apply when reviewing others' code with AI assistance: you must personally read and understand every comment you post. Raw AI review output is often verbose and cluttered with trivial details, placing a heavy cognitive load on others to figure out what is actually being asked. If you use AI to assist your reviews, please filter out irrelevant points or details you do not understand, and rephrase the rest in your own words so that each comment delivers clear, actionable, and specific feedback. + +--- + +## Better Ways to Contribute + +Rather than hastily submitting an unreviewed AI code patch, we strongly encourage opening a **high-quality issue** instead: describe the problem in clear terms and provide a **minimal, reproducible example (MRE)** focused on end-user-visible behavior. This significantly reduces the investigation burden on maintainers and lays a solid foundation for effective collaboration. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b641743ed0..2308cff691 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,6 +84,41 @@ Any contribution of test cases is encouraged, especially unit tests. It is recom Documentation is an important component of the project official website and serves as a vital bridge between the project and the community. Please refer to [Docs Contribution](https://fesod.apache.org/community/contribution/contribute-doc/) for information on how to contribute code. +## AI Policy + +All AI-assisted contributions must adhere to our [AI Policy](./AI_POLICY.md). + +## PR Adoption + +To prevent long-stalled pull requests (PRs) from blocking project progress while respecting the original authors' hard work, the community supports adopting inactive PRs. + +### 1. Applicability + +The PR adoption mechanism applies when **all** of the following conditions are met: + +- **Review is progressing normally**: Reviewers have actively provided feedback and reviews; the stall is not due to a lack of community review capacity. +- **Long author inactivity**: The original author has been inactive for over **14 days** without addressing required items (e.g., unresolved CI failures, unanswered review comments, unmerged branch conflicts, or explicitly stating they have no time to proceed). +- **Adoption intent stated**: Another contributor has actively commented in the original PR expressing interest in taking it over. + +### 2. Workflow + +1. **Polite Inquiry**: After the adopter leaves a comment in the original PR confirming their intent to take over, maintainers may add the `PR: waiting for feedback` label. +2. **Grace Period**: Give the original author a **7-day** grace period. + - **Resume work**: If the original author resumes work with meaningful progress (e.g., addressing review questions, pushing code, or providing a clear schedule), the adoption process terminates, giving priority to the original author to finish. + - **Early hand-off**: If the original author explicitly states they cannot continue, the new contributor may take over immediately without waiting for the 7 days to expire. + - **Timeout**: If the author does not respond or show meaningful progress by the end of the 7-day window, the new contributor may proceed to work and submit a new PR. +3. **Link & Track**: At the beginning of the new PR description, please state `Related #` and apply the `PR: adopted` label. Maintainers will close the original PR with gratitude once the new PR is merged or the new approach is confirmed. + +### 3. Attribution + +- **Code reuse**: The new PR **must preserve the original author's contribution**. Retain original commits whenever possible, and append the following to the end of the commit message: `Co-authored-by: Name ` +- **Full rewrite**: Preserving original commits is not required, but you **must link to the original PR in your PR description**. + +### 4. Anti-Poaching + +- **Premature Takeover**: If someone opens a new PR prematurely before the grace period expires, maintainers will **suspend reviewing the new PR** until the waiting period ends. +- **Unwanted Takeover**: If the original author is still actively following up and a third party insists on opening a competing PR, maintainers **reserve the right to close the new PR immediately**. + ## Other Ways to Contribute Apart from directly contributing code, the following ways are also valuable support for Apache Fesod (Incubating): diff --git a/website/community/contribution.md b/website/community/contribution.md index e2063ab5ce..80f3978886 100644 --- a/website/community/contribution.md +++ b/website/community/contribution.md @@ -87,6 +87,41 @@ Any contribution of test cases is encouraged, especially unit tests. It is recom Documentation is an important component of the project official website and serves as a vital bridge between the project and the community. Please refer to [Docs Contribution](./contribution/contribute-doc.md) for information on how to contribute document. +## AI Policy + +All AI-assisted contributions must adhere to our [AI Policy](./contribution/ai-policy.md). + +## PR Adoption + +To prevent long-stalled pull requests (PRs) from blocking project progress while respecting the original authors' hard work, the community supports adopting inactive PRs. + +### Applicability + +The PR adoption mechanism applies when **all** of the following conditions are met: + +- **Review is progressing normally**: Reviewers have actively provided feedback and reviews; the stall is not due to a lack of community review capacity. +- **Long author inactivity**: The original author has been inactive for over **14 days** without addressing required items (e.g., unresolved CI failures, unanswered review comments, unmerged branch conflicts, or explicitly stating they have no time to proceed). +- **Adoption intent stated**: Another contributor has actively commented in the original PR expressing interest in taking it over. + +### Workflow + +1. **Polite Inquiry**: After the adopter leaves a comment in the original PR confirming their intent to take over, maintainers may add the `PR: waiting for feedback` label. +2. **Grace Period**: Give the original author a **7-day** grace period. + - **Resume work**: If the original author resumes work with meaningful progress (e.g., addressing review questions, pushing code, or providing a clear schedule), the adoption process terminates, giving priority to the original author to finish. + - **Early hand-off**: If the original author explicitly states they cannot continue, the new contributor may take over immediately without waiting for the 7 days to expire. + - **Timeout**: If the author does not respond or show meaningful progress by the end of the 7-day window, the new contributor may proceed to work and submit a new PR. +3. **Link & Track**: At the beginning of the new PR description, please state `Related #` and apply the `PR: adopted` label. Maintainers will close the original PR with gratitude once the new PR is merged or the new approach is confirmed. + +### Attribution + +- **Code reuse**: The new PR **must preserve the original author's contribution**. Retain original commits whenever possible, and append the following to the end of the commit message: `Co-authored-by: Name ` +- **Full rewrite**: Preserving original commits is not required, but you **must link to the original PR in your PR description**. + +### Anti-Poaching + +- **Premature Takeover**: If someone opens a new PR prematurely before the grace period expires, maintainers will **suspend reviewing the new PR** until the waiting period ends. +- **Unwanted Takeover**: If the original author is still actively following up and a third party insists on opening a competing PR, maintainers **reserve the right to close the new PR immediately**. + ## Other Ways to Contribute Apart from directly contributing code, the following ways are also valuable support for Apache Fesod (Incubating): diff --git a/website/community/contribution/ai-policy.md b/website/community/contribution/ai-policy.md new file mode 100644 index 0000000000..6f7faaffed --- /dev/null +++ b/website/community/contribution/ai-policy.md @@ -0,0 +1,50 @@ +--- +id: 'ai-policy' +title: 'AI Policy' +--- + + + +# AI Policy + +We welcome contributors using AI as a tool for coding and learning. However, **using tools does not replace human thought and responsibility**. Every contributor remains ultimately responsible for the code and comments they submit. + +A core value of open source is **human collaboration, knowledge sharing, and trust**. Maintainer review capacity is very limited; we cannot accept a dynamic where reviewers become proxies driving or debugging the contributor's AI tool. To ensure project quality and efficient community collaboration, please adhere to the following guidelines: + +## Pull Request + +- Before submitting a PR, the author must personally read the code, understand the core design end-to-end, and be able to clearly explain their changes during review. Submitting unverified or undigested content is strictly prohibited; even if the code runs, an author who cannot explain its principles is essentially offloading the entire burden of comprehension and verification onto reviewers, and the author gains no growth from the process. +- It is completely normal to not fully understand every detail of AI-generated code. Please proactively call out these unknowns and assumptions in your PR description so reviewers can work with you to address any concerns. +- We strictly prohibit automatic, unattended, bot-owned, or bulk submissions that lack meaningful human review. We require every submission to have a human in the loop who genuinely understands the work produced by AI and takes personal responsibility for it. +- All contributions must strictly comply with the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html). + +## Communication & Discussion + +Code review is not just about merging code; it is about engaging with **you as a person** (rather than your AI tool) to help you grow and integrate into the community. Whether opening an issue, describing a PR, or answering questions during review, please express yourself in your own words, and never copy-paste unreviewed, AI-generated content directly. + +Unreviewed AI replies place the burden of discernment entirely on the reviewer and deny you the opportunity to learn. Common examples of such unhelpful replies include mechanically summarizing the diff instead of addressing the actual question, listing local commands and checks that CI already covers, or evading design questions with generic descriptions of code changes. + +We fully understand that non-native English speakers may use AI for reading, polishing, or translating comments. Using AI to assist with language is completely acceptable, provided the final text accurately reflects your own voice, ideas, and intent. + +## AI-Assisted Reviews + +The same standards apply when reviewing others' code with AI assistance: you must personally read and understand every comment you post. Raw AI review output is often verbose and cluttered with trivial details, placing a heavy cognitive load on others to figure out what is actually being asked. If you use AI to assist your reviews, please filter out irrelevant points or details you do not understand, and rephrase the rest in your own words so that each comment delivers clear, actionable, and specific feedback. + +## Better Ways to Contribute + +Rather than hastily submitting an unreviewed AI code patch, we strongly encourage opening a **high-quality issue** instead: describe the problem in clear terms and provide a **minimal, reproducible example (MRE)** focused on end-user-visible behavior. This significantly reduces the investigation burden on maintainers and lays a solid foundation for effective collaboration. diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution.md index 708cc01246..a76fb16014 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution.md @@ -86,6 +86,41 @@ title: '概述' 文档是 Apache Fesod (Incubating) 官方网站的重要构建内容,是项目与社区之间的重要桥梁。请参考[文档贡献指南](./contribution/contribute-doc.md)了解如何贡献文档。 +## AI 辅助贡献指南 + +所有借助 AI 辅助的贡献都必须严格遵守我们的 [AI 辅助贡献指南](./contribution/ai-policy.md)。 + +## 非活跃 PR 接手指南 + +为避免长期停滞的 PR 阻塞项目演进,同时充分尊重原作者的劳动成果,社区支持对停滞 PR 进行接手与认领。 + +### 适用条件 + +当**同时满足**以下所有情况时,适用 PR 接手机制: + +- **审查正常推进**:Reviewers 已积极跟进审查并给出反馈,PR 停滞并非因社区缺乏 Review 资源所致。 +- **作者端长期未响应**:原作者超过 **14 天** 未处理必要事项(如:CI 失败未修复、Review 意见未回复、分支严重冲突未解决,或公开表示无暇推进)。 +- **已有接管意向**:已有其他贡献者在原 PR 评论区主动留言,明确表达了接手意向。 + +### 接手流程 + +1. **礼貌询问**:接管人在原 PR 留言确认接手意向后,维护者可以为原 PR 添加 `PR: waiting for feedback` 标签。 +2. **等待缓冲期**:给予原作者 **7 天缓冲期**。 + - **恢复推进**:若原作者在期内取得实质性进展(如回复 Review 疑问、提交修改代码,或提供明确的排期计划),接管流程终止,优先留给原作者完成; + - **提前交接**:若原作者明确表示无暇继续推进,新贡献者可**立即接手**,无需等满 7 天; + - **超时处理**:若 7 天期满仍未回复或无实质性进展,新贡献者可正式开展工作并提交新 PR。 +3. **关联与追踪**:新 PR 描述开头请注明 `Related #<原PR编号>`,并添加 `PR: adopted` 标签。新 PR 合并或确认替代方案有效后,维护者将关闭原 PR 并致谢。 + +### 署名与致敬 + +- **代码复用**:新 PR **必须保留原作者的贡献**。优先保留原 Commits;并在提交信息末尾附上:`Co-authored-by: 原作者名 <原作者邮箱>`。 +- **完全重写**:无需保留原 Commit,但**必须在 PR 描述中链接原 PR**,致敬前期的探索。 + +### 防抢跑与公平原则 + +- **抢跑行为**:若有人在缓冲期满前擅自开启新 PR 抢跑,维护者将**暂缓审查该新 PR**,直至等待期结束。 +- **恶意竞争**:若原作者仍在积极跟进,第三方仍执意开启新 PR 竞争的,维护者**有权直接关闭该新 PR**。 + ## 其他参与方式 除了直接贡献代码,以下方式同样是对 Apache Fesod (Incubating) 的宝贵支持: diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution/ai-policy.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution/ai-policy.md new file mode 100644 index 0000000000..21e8f8e365 --- /dev/null +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/contribution/ai-policy.md @@ -0,0 +1,50 @@ +--- +id: 'ai-policy' +title: 'AI 辅助贡献指南' +--- + + + +# AI 辅助贡献指南 + +我们欢迎贡献者使用 AI 作为辅助编码与学习的工具。然而,**工具的使用不能替代人类的思考与责任**。每一位贡献者都必须对自己提交的代码与言论承担最终责任。 + +开源社区的核心价值之一是**人与人之间的协作、知识共享与信任**。维护者的审查资源非常有限,我们无法接受维护者沦为“替贡献者操作/调试 AI”的代理人。为了保障项目质量与社区协作效率,请遵守以下规范: + +## Pull Request + +- 提交 PR 前,作者必须亲自通读代码,端到端理解核心设计思路,并能在 Review 过程中阐明自己的修改。严禁提交未经自身消化与验证的内容;即使代码可以跑通,作者若无法解释其原理,本质上是将理解与核实的成本全甩给了 Reviewers,作者自己也无法获得任何提升。 +- 若未能完全吃透 AI 生成代码的某一处细节是完全正常的。请在 PR 描述中主动标明这些未知点与前提假设,以便 Reviewers 能够与你共同探讨并排查隐患。 +- 严禁提交缺乏实质性人工审查的全自动、无人值守、Bot 主导或批量生成的 PR。我们要求每一项提交都必须有能够充分理解 AI 产出的人类亲自把关并负责。 +- 所有贡献必须严格遵循 [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html)。 + +## 沟通与讨论 + +代码审查不仅是为了合并代码,更是为了与**你本人**(而非你的 AI 工具)交流,帮助你融入社区并共同成长。无论是创建 Issue 描述问题、撰写 PR 说明,还是在审查过程中回复提问,都请务必使用你自己的语言表达,切勿直接照搬未经审核的 AI 生成内容。 + +未经消化的 AI 回复不仅将甄别与理解的负担完全推给了 Reviewers,也让你失去了交流与成长的机会。这类无效回复的典型特征包括:机械地复述代码变更却对核心提问答非所问、罗列 CI 早已自动覆盖的本地命令与检查结果,或者用泛泛的代码修改描述来回避具体的设计疑问。 + +我们非常理解非英语母语者使用 AI 辅助阅读、润色或翻译评论的需求。只要最终生成的内容能够真实反映你个人的思考与想法,使用 AI 协助语言表达是完全被接受的。 + +## AI 辅助参与审查 + +使用 AI 协助审查他人代码时同样适用上述标准:你必须亲自通读并完全理解自己发出的每一条意见。未经提炼的 AI 原始审查意见往往冗长且充斥着琐碎细节,会耗费他人大量精力去分辨核心诉求。如果你借助 AI 辅助 Review,请务必先过滤掉无关或自己不理解的内容,并用自己的语言重新组织,确保每条评论都能给出清晰、具体且可落地的改进建议。 + +## 更好的贡献方式 + +与其草率地抛出一个未经消化的 AI 代码补丁,我们更鼓励你提交一份**高质量的 Issue**:用清晰的语言描述问题,并提供聚焦于终端用户可见行为的**最小可复现用例(MRE)**。这不仅能极大减轻维护者的排查负担,也为后续高效的社区协作打下坚实的基础。 diff --git a/website/sidebarsCommunity.js b/website/sidebarsCommunity.js index 2d413002e5..0b29275d01 100644 --- a/website/sidebarsCommunity.js +++ b/website/sidebarsCommunity.js @@ -46,6 +46,7 @@ const sidebarsCommunity = { 'contribution', 'contribution/commit-format', 'contribution/contribute-code', + 'contribution/ai-policy', 'contribution/contribute-doc', 'contribution/code-review-guide', ]