Skip to content
11 changes: 11 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
53 changes: 53 additions & 0 deletions AI_POLICY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-->

# 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.
35 changes: 35 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 #<Original-PR-Number>` 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 <email>`
- **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):
Expand Down
35 changes: 35 additions & 0 deletions website/community/contribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 #<Original-PR-Number>` 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 <email>`
- **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):
Expand Down
50 changes: 50 additions & 0 deletions website/community/contribution/ai-policy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
id: 'ai-policy'
title: 'AI Policy'
---

<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-->

# 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.
Original file line number Diff line number Diff line change
Expand Up @@ -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) 的宝贵支持:
Expand Down
Loading
Loading