You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by "corgy-w (via GitHub)" <gi...@apache.org> on 2026/01/28 15:37:45 UTC
[PR] [Docs] Add LLM contribution guide [seatunnel]
corgy-w opened a new pull request, #10411:
URL: https://github.com/apache/seatunnel/pull/10411
<!--
Thank you for contributing to SeaTunnel! Please make sure that your code changes
are covered with tests. And in case of new features or big changes
remember to adjust the documentation.
Feel free to ping committers for the review!
## Contribution Checklist
- Make sure that the pull request corresponds to a [GITHUB issue](https://github.com/apache/seatunnel/issues).
- Name the pull request in the form "[Feature] [component] Title of the pull request", where *Feature* can be replaced by `Hotfix`, `Bug`, etc.
- Minor fixes should be named following this pattern: `[hotfix] [docs] Fix typo in README.md doc`.
-->
### Purpose of this pull request
This PR introduces `AGENTS.md` (and its Chinese version `AGENTS_ZH.md`) to the repository root.
**Motivation:**
As AI coding assistants (like Cursor, Windsurf, Trae, etc.) are becoming more popular, having a dedicated context file helps them understand the project structure, coding standards, and testing procedures of Apache SeaTunnel. This file mirrors the `AGENTS.md` practice found in other mature Apache projects (e.g., Apache Superset) but adapts it specifically to SeaTunnel's engineering conventions.
**Key contents of AGENTS.md:**
- **Critical Requirements**: Validation steps (Spotless, Verify, Test) before pushing.
- **Git Convention**: Standardized commit message format.
- **Project Structure**: Overview of key modules like `seatunnel-connectors-v2` and `seatunnel-engine`.
- **Tech Stack**: Rules for dependencies (e.g., using shaded packages) and code style.
- **Testing Strategy**: Guidelines for Unit Tests and E2E Tests.
- **Documentation**: Requirement for bilingual (EN/ZH) updates.
<!-- Describe the purpose of this pull request. For example: This pull request adds checkstyle plugin.-->
### Does this PR introduce _any_ user-facing change?
<!--
Note that it means *any* user-facing change including all aspects such as the documentation fix.
If yes, please clarify the previous behavior and the change this PR proposes - provide the console output, description and/or an example to show the behavior difference if possible.
If possible, please also clarify if this is a user-facing change compared to the released SeaTunnel versions or within the unreleased branches such as dev.
If no, write 'No'.
If you are adding/modifying connector documents, please follow our new specifications: https://github.com/apache/seatunnel/issues/4544.
-->
### How was this patch tested?
<!--
If tests were added, say they were added here. Please make sure to add some test cases that check the changes thoroughly including negative and positive cases if possible.
If it was tested in a way different from regular unit tests, please clarify how you tested step by step, ideally copy and paste-able, so that other reviewers can test and check, and descendants can verify in the future.
If tests were not added, please describe why they were not added and/or why it was difficult to add.
If you are adding E2E test cases, maybe refer to https://github.com/apache/seatunnel/blob/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-cdc-mysql-e2e/src/test/resources/mysqlcdc_to_mysql.conf, here is a good example.
-->
### Check list
* [ ] If any new Jar binary package adding in your PR, please add License Notice according
[New License Guide](https://github.com/apache/seatunnel/blob/dev/docs/en/contribution/new-license.md)
* [ ] If necessary, please update the documentation to describe the new feature. https://github.com/apache/seatunnel/tree/dev/docs
* [ ] If necessary, please update `incompatible-changes.md` to describe the incompatibility caused by this PR.
* [ ] If you are contributing the connector code, please check that the following files are updated:
1. Update [plugin-mapping.properties](https://github.com/apache/seatunnel/blob/dev/plugin-mapping.properties) and add new connector information in it
2. Update the pom file of [seatunnel-dist](https://github.com/apache/seatunnel/blob/dev/seatunnel-dist/pom.xml)
3. Add ci label in [label-scope-conf](https://github.com/apache/seatunnel/blob/dev/.github/workflows/labeler/label-scope-conf.yml)
4. Add e2e testcase in [seatunnel-e2e](https://github.com/apache/seatunnel/tree/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/)
5. Update connector [plugin_config](https://github.com/apache/seatunnel/blob/dev/config/plugin_config)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "corgy-w (via GitHub)" <gi...@apache.org>.
corgy-w commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2744368937
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
Review Comment:
The DOC doesn't have [Module], so I think this is fine. I feel there's no need to add anything here
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2737277651
##########
agent/AGENTS.md:
##########
@@ -0,0 +1,240 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
+
+## Repository Structure
+
+```text
+seatunnel/
+├── seatunnel-api/ # Core API definitions
+├── seatunnel-connectors-v2/ # Source & Sink connectors (main contribution area)
+├── seatunnel-transforms-v2/ # Transform plugins (including LLM)
+├── seatunnel-engine/ # Zeta engine & Web UI
+├── seatunnel-core/ # Job submission & CLI entry points
+├── seatunnel-translation/ # Flink & Spark adapters
+├── seatunnel-formats/ # Data formats (JSON, Avro, etc.)
+├── seatunnel-e2e/ # End-to-End integration tests
+├── docs/ # Documentation (en & zh)
+└── config/ # Default configurations
+```
+
+## Code Standards
+
+### Java Backend
+
+* **Formatting**: Google Java Format (AOSP style), enforced by Spotless
+* **Imports**:
+
+ * No wildcard imports
+ * Use shaded dependencies: `org.apache.seatunnel.shade.*`
+* **Nullability**: Avoid implicit null assumptions
+* **Visibility**: Keep APIs minimal; prefer package-private when possible
+
+### Apache License Header (MANDATORY)
+
+All **new files** MUST include the ASF license header:
+
+```java
+/*
+ * 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.
+ */
+```
+
+## 🚨 Backward Compatibility (VERY IMPORTANT)
+
+Agents MUST treat backward compatibility as a **hard constraint**.
+
+* DO NOT remove or rename existing config options
+* DO NOT change default values casually
+* DO NOT break public APIs or SPI contracts
+
+Any incompatible change MUST:
+
+* Be explicitly documented
Review Comment:
Incompatible changes should be documented in `docs/en/introduction/concepts/incompatible-changes.md`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2744386607
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
Review Comment:
It is recommended to supplement DOC doesn't have [Module] in this description.
<img width="1355" height="390" alt="image" src="https://github.com/user-attachments/assets/54e8ff09-ad38-49bb-80eb-c237b58f21d8" />
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "DanielCarter-stack (via GitHub)" <gi...@apache.org>.
DanielCarter-stack commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3815813416
<!-- code-pr-reviewer -->
<!-- cpr:pr_reply_v2_parts {"group": "apache/seatunnel#10411", "part": 1, "total": 1} -->
### Issue 1: Missing Chinese version of documentation `AGENTS_ZH.md`
**Location**: Root directory
```bash
# Files promised but not created in PR
AGENTS_ZH.md
```
**Related Context**:
- PR description explicitly states: "This PR introduces `AGENTS.md` (and its Chinese version `AGENTS_ZH.md`)"
- Project documentation standards require: "Any user-visible change MUST update: `docs/en` AND `docs/zh`"
- Existing Chinese documentation directory: `docs/zh/` exists with complete structure
**Issue Description**:
The PR description explicitly promises to create a Chinese version `AGENTS_ZH.md`, but the actual changes only create an English version `AGENTS.md` and three symlinks. This violates:
1. The explicit promise in the PR description
2. The project's own bilingual documentation standards (also mentioned in AGENTS.md lines 170-177)
**Potential Risks**:
- Risk 1: Chinese contributors using AI assistants may not receive optimal guidance
- Risk 2: Violates the project's bilingual documentation convention, causing inconsistent documentation structure
- Risk 3: May set a wrong example for other contributors to "ignore Chinese documentation"
**Impact Scope**:
- Direct impact: Chinese contributors and developers using Chinese AI models
- Indirect impact: Project internationalization strategy and documentation consistency
- Impact level: Project-level (documentation standards)
**Severity**: MAJOR
**Improvement Suggestions**:
```bash
# Option 1: Create AGENTS_ZH.md (recommended)
# Need to translate AGENTS.md to Chinese, keeping structure consistent
# Option 2: Create symlink to English version (temporary solution)
ln -s AGENTS.md AGENTS_ZH.md
# But this is not a good long-term solution
# Option 3: Defer to follow-up PR
# Clearly state in PR description that Chinese version will be added in follow-up PR
# Need to create Issue to track
```
**Rationale**: The project has clear bilingual documentation standards, and the PR description promised a Chinese version. Suggest supplementing before merge, or explicitly stating the plan for the Chinese version in the PR description.
---
### Issue 2: Startup script path error
**Location**: `AGENTS.md:233-237`
```markdown
### Run Job (Zeta)
```bash
sh bin/seatunnel.sh --config config/v2.batch.config.template -e local
```
```
** **Related Context:
- 实际 seatunnel.sh 位置:`seatunnel-core/seatunnel-starter/src/main/bin/seatunnel.sh`
- config 模板位置:`config/v2.batch.config.template` ✓ 存在
- 文档声称的路径:`bin/seatunnel.sh` ✗ 不存在
** **Problem Description:
文档中提供的运行命令使用了错误的路径。`bin/` 目录下只有 `install-plugin.sh`,没有 `seatunnel.sh`。实际的 `seatunnel.sh` 位于 `seatunnel-core/seatunnel-starter/src/main/bin/`。
这会导致:
1. 新手直接复制命令会失败
2. AI 助手可能生成错误的运行脚本
3. 降低文档的可信度
** **Potential Risks:
- 风险 1:开发者尝试运行命令时会报错 "No such file or directory"
- 风险 2:浪费开发者时间排查路径问题
- 风险 3:AI 助手可能学习到错误的路径模式
** **Impact Scope:
- 直接影响:尝试运行 SeaTunnel 的开发者
- 间接影响:文档可信度
- 影响面:使用 Zeta 引擎的用户
** **Severity:** MAJOR
** **Improvement Suggestions:
```markdown
### Run Job (Zeta)
**After building from source**, you can run a job using:
```bash
# ## Issue 3: Incomplete directory structure description
** **Location:** `AGENTS.md:60-74`
```markdown
## Repository Structure
```text
seatunnel/
├── seatunnel-api/ # Core API definitions
├── seatunnel-connectors-v2/ # Source & Sink connectors (main contribution area)
├── seatunnel-transforms-v2/ # Transform plugins (including LLM)
├── seatunnel-engine/ # Zeta engine & Web UI
├── seatunnel-core/ # Job submission & CLI entry points
├── seatunnel-translation/ # Flink & Spark adapters
├── seatunnel-formats/ # Data formats (JSON, Avro, etc.)
├── seatunnel-e2e/ # End-to-End integration tests
├── docs/ # Documentation (en & zh)
└── config/ # Default configurations
```
```
** **Related Context:
- 实际存在的模块(通过 `ls -d seatunnel-*` 确认):
- `seatunnel-api` ✓
- `seatunnel-connectors-v2` ✓
- `seatunnel-transforms-v2` ✓
- `seatunnel-engine` ✓
- `seatunnel-core` ✓
- `seatunnel-translation` ✓
- `seatunnel-formats` ✓
- `seatunnel-e2e` ✓
- `seatunnel-common` ✗(未列出)
- `seatunnel-config` ✗(未列出)
- `seatunnel-dist` ✗(未列出)
- `seatunnel-examples` ✗(未列出)
- `seatunnel-plugin-discovery` ✗(未列出)
- `seatunnel-shade` ✗(未列出)
- `seatunnel-ci-tools` ✗(未列出)
** **Problem Description:
文档中列出的目录结构不完整,遗漏了 7 个子模块。虽然文档说明是"Overview of key modules",但:
1. 没有明确说明这是"非完整列表"
2. `seatunnel-common` 是一个核心模块(公共工具类),被遗漏不太合理
3. `seatunnel-dist` 与打包分发相关,也可能被贡献者接触到
** **Potential Risks:
- 风险 1:AI 助手可能认为只有这 9 个模块,在实际修改时遗漏其他模块
- 风险 2:贡献者在需要修改 `seatunnel-common` 时,可能不知道这个模块的存在
- 风险 3:可能误导 AI 助手进行模块推荐
** **Impact Scope:
- 直接影响:需要修改被遗漏模块的贡献者
- 间接影响:AI 助手的模块推荐准确性
- 影响面:多模块
** **Severity:** MINOR
** **Improvement Suggestions:
```markdown
## Repository Structure
```text
seatunnel/
├── seatunnel-api/ # Core API definitions
├── seatunnel-common/ # Common utilities and shared code
├── seatunnel-config/ # Configuration module
├── seatunnel-connectors-v2/ # Source & Sink connectors (main contribution area)
├── seatunnel-transforms-v2/ # Transform plugins (including LLM)
├── seatunnel-engine/ # Zeta engine & Web UI
├── seatunnel-core/ # Job submission & CLI entry points
├── seatunnel-translation/ # Flink & Spark adapters
├── seatunnel-formats/ # Data formats (JSON, Avro, etc.)
├── seatunnel-e2e/ # End-to-End integration tests
├── seatunnel-dist/ # Distribution packaging
├── seatunnel-shade/ # Shaded dependencies
├── seatunnel-plugin-discovery/ # Plugin discovery mechanism
├── seatunnel-ci-tools/ # CI/CD tools
├── seatunnel-examples/ # Example configurations
├── docs/ # Documentation (en & zh)
└── config/ # Default configurations
```
**Key modules for contributors**:
- **Connector-V2**: Most contributions happen here
- **Transform-V2**: Data transformation plugins
- **Zeta (seatunnel-engine)**: Engine development
- **E2E**: Integration tests
```
** **Reasoning:
1. 列出所有模块,提供完整的视图
2. 添加简短描述说明每个模块的用途
3. 强调"Key modules for contributors",帮助贡献者聚焦
4. 保持简洁,但提供完整信息
---
# ## Issue 4: Git commit format differs from actual history
** **Location:** `AGENTS.md:22-58`
** **Related Context:
- 文档声称的格式:`[Type][Module] Description`
- 实际历史中的变体:
- `[Docs] Add LLM contribution guide`(无模块)✓ 符合
- `[Fix][Connector-V2][Hive] ...`(三级标签)⚠️ 变体
- `[Fix] [connector-hbase] ...`(小写+空格)⚠️ 变体
- `[Feature] [Connector-file] ...`(空格)⚠️ 变体
- `[Bug][Connector-V2] ...`(使用 Bug)⚠️ 类型不一致
** **Problem Description:
文档中定义的提交格式是"理想格式",但项目实际历史中存在多种变体:
1. 模块标签有时使用小写(如 `connector-hbase` vs `Connector-V2`)
2. 有时使用三级标签(如 `[Fix][Connector-V2][Hive]`)
3. 有时标签之间有空格(`[Fix] [connector-hbase]`)
4. 类型有时使用 `Bug` 而非 `Fix`
5. 有些提交没有模块标签(如 `[Docs] ...`)
文档没有说明这些变体是否可接受,可能导致 AI 助手或贡献者困惑。
** **Potential Risks:
- 风险 1:AI 助手可能拒绝接受历史中的合法提交格式
- 风险 2:贡献者可能认为历史提交格式"错误"
- 风险 3:缺乏明确的规范说明,导致新贡献者不知道该遵循哪个格式
** **Impact Scope:
- 直接影响:Git 提交信息格式
- 间接影响:提交历史的一致性
- 影响面:项目级
** **Severity:** MINOR
** **Improvement Suggestions:
```markdown
## Git Commit Message Convention
SeaTunnel follows a **standardized commit message format** to maintain a clean and searchable history.
**Recommended Format**:
```
[Type][Module] Description
```
**Allowed Variations**:
- `[Type] Description` (without module tag, for general changes)
- `[Type][Module][Sub-module] Description` (for specific sub-components)
**Type Values** (case-sensitive, prefer these):
* `Feature` – New features
* `Fix` – Bug fixes (also `Bug` is accepted but discouraged)
* `Improve` – Improvements to existing behavior
* `Docs` – Documentation-only changes
* `Test` – Test cases or test framework changes
* `Chore` – Build, dependency, or maintenance tasks
**Module Values** (use consistent casing):
* `Connector-V2` – seatunnel-connectors-v2
* `Zeta` – seatunnel-engine (Zeta engine)
* `Core` – seatunnel-core
* `API` – seatunnel-api
* `Transform-V2` – seatunnel-transforms-v2
* `Format` – seatunnel-formats
* `Translation` – seatunnel-translation
* `E2E` – seatunnel-e2e
**Examples**:
* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
* `[Feature][Transform-V2] Add LLM transform plugin`
* `[Docs] Update quick start guide`
* `[Improve][Core] Optimize jar package loading speed`
**Historical Note**: Some historical commits use variations like lowercase module names (`connector-hbase`), extra spaces (`[Fix] [module]`), or `Bug` instead of `Fix`. New commits should follow the recommended format above.
```
** **Reasoning:
1. 明确区分"推荐格式"和"允许变体"
2. 说明历史差异,避免混淆
3. 提供清晰的指导,告诉新贡献者应该怎么做
4. 保持向后兼容性,承认历史格式的合理性
---
# ## Issue 5: Documentation location may not be prominent enough
** **Location:** Root directory `AGENTS.md`
** **Related Context:
- 文件放置在项目根目录
- 与 `README.md` 同级
- 没有在 `README.md` 中引用或提及
- 没有在 `docs/` 目录中建立索引
** **Problem Description:
虽然 `AGENTS.md` 放在根目录有助于 LLM 工具发现,但对于人类贡献者来说:
1. 没有在 README 中提及,可能不容易被发现
2. 不在 docs/ 目录下,可能不被视为"正式文档"
3. 没有在文档导航中集成
** **Potential Risks:
- 风险 1:人类贡献者可能不知道这个文档的存在
- 风险 2:文档可能长期不更新,因为没人知道要更新它
- 风险 3:与 `docs/` 目录的隔离可能导致内容重复或冲突
** **Impact Scope:
- 直接影响:文档的可发现性
- 间接影响:文档的维护和更新
- 影响面:项目级
** **Severity:** MINOR
** **Improvement Suggestions:
** **Option 1: Add reference in README.md (recommended)
```markdown
# Add to the "Contributing" section in README.md
## Contributing
We welcome contributions! Please check out:
- [Contribution Guide](docs/en/contribution/...) (for humans)
- [LLM Context Guide](AGENTS.md) (for AI assistants like Claude, GPT, etc.)
```
** **Option 2: Add link in docs/ as well
```bash
# Create docs/en/AGENTS.md (symlink or redirect)
ln -s ../../AGENTS.md docs/en/AGENTS.md
# Create docs/zh/AGENTS_ZH.md
ln -s ../../AGENTS_ZH.md docs/zh/AGENTS_ZH.md
```
** **Option 3: Add to documentation sidebar
在 `docs/sidebars.js` 中添加:
```javascript
{
type: 'link',
label: 'For AI Assistants',
href: '/en/AGENTS',
}
```
** **Reasoning:
1. 提高文档的可发现性
2. 让人类贡献者也知道这个资源
3. 建立与正式文档体系的连接
4. 便于未来维护和更新
---
# ## Issue 6: Missing CI/CD workflow documentation
** **Location:** `AGENTS.md` (overall)
** **Related Context:
- 文档提到了本地验证命令(`./mvnw spotless:apply`, `./mvnw verify`, `./mvnw test`)
- 但没有提及 CI/CD 流程
- 项目有 `.github/workflows/` 目录(GitHub Actions)
** **Problem Description:
现代开源项目通常有 CI/CD 流程自动检查 PR。文档中:
1. 没有说明 PR 提交后 CI 会自动运行哪些检查
2. 没有说明如何查看 CI 结果
3. 没有说明 CI 失败后如何处理
4. 没有说明如何在本地模拟 CI 检查
** **Potential Risks:
- 风险 1:贡献者可能不知道 CI 会自动检查
- 风险 2:贡献者可能不知道如何理解 CI 错误
- 风险 3:AI 助手可能生成无法通过 CI 的代码
** **Impact Scope:
- 直接影响:PR 提交流程
- 间接影响:PR 合并效率
- 影响面:所有贡献者
** **Severity:** MINOR
** **Improvement Suggestions:
```markdown
## CI/CD Process
**Automated Checks**:
When you open a PR, GitHub Actions will automatically run:
- Spotless format check
- Compilation (verify)
- Unit tests
- E2E tests (for some modules)
**Viewing CI Results**:
1. Go to your PR page
2. Scroll to the "Checks" section at the bottom
3. Click on the failed job to see detailed logs
**Common CI Failures**:
- **Spotless check failed**: Run `./mvnw spotless:apply` and push again
- **Test failed**: Check the test logs, fix the issue, and push
- **Compilation failed**: Check the compiler error logs
**Running CI Locally** (optional):
```bash
# ## Issue 7: E2E test command may be inaccurate
** **Location:** `AGENTS.md:193-203`
** **Related Context:
- 文档声称:
```bash
./mvnw -DskipUT -DskipIT=false verify
```
- 这个命令会跳过单元测试(skipUT),但运行集成测试
** **Problem Description:
1. 命令名称叫 "E2E Tests",但实际使用 `-DskipIT=false`,这是运行集成测试,不一定是 E2E 测试
2. E2E 测试可能位于 `seatunnel-e2e` 模块,需要特定的命令运行
3. 文档没有说明如何运行特定模块的 E2E 测试
** **Potential Risks:
- 风险 1:AI 助手可能无法正确区分 E2E 测试和集成测试
- 风险 2:贡献者可能无法运行特定的 E2E 测试
- 风险 3:测试运行失败时不知道如何排查
** **Impact Scope:
- 直接影响:测试运行
- 间接影响:PR 质量保证
- 影响面:Connector-V2 和其他需要 E2E 测试的模块
** **Severity:** MINOR
** **Improvement Suggestions:
```markdown
### E2E Tests
* Located in `seatunnel-e2e`
* Uses Testcontainers for real environment testing
* Extend `TestSuiteBase` for consistent test setup
**Run all E2E tests**:
```bash
./mvnw -DskipUT -DskipIT=false verify
```
**Run specific E2E test**:
```bash
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "corgy-w (via GitHub)" <gi...@apache.org>.
corgy-w commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2744391761
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
Review Comment:
get
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3812075082
Good practice for AI coding
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "corgy-w (via GitHub)" <gi...@apache.org>.
corgy-w commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2744393424
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
Review Comment:
Then I think it’s better to use Doc as [Module] as before.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "chl-wxp (via GitHub)" <gi...@apache.org>.
chl-wxp commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3814858240
Isn’t Chinese documentation in the plan?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3817365299
Can you remind the AI to add comments for important methods? I find out that the comments in the current code are rare.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2758923686
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
Review Comment:
```suggestion
# Unit tests (strongly recommended)
./mvnw test -nsu
# Check for compilation errors in affected modules
./mvnw clean package -pl <affected-module> -am -nsu
```
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2744386607
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
Review Comment:
I think we could add DOC doesn't have [Module] to this description, but it’s totally fine to leave it out—this isn’t something we need to overthink.
<img width="1355" height="390" alt="image" src="https://github.com/user-attachments/assets/54e8ff09-ad38-49bb-80eb-c237b58f21d8" />
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3821451987
> > Isn’t Chinese documentation in the plan?
>
> @chl-wxp I took a look at the loading logic of commonly used tools. It's all unnecessary to load Chinese items like AGENT/GPT in the root directory
<img width="1323" height="335" alt="image" src="https://github.com/user-attachments/assets/12765776-c962-4137-b758-99fbdd369807" />
This can be removed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2758923686
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
Review Comment:
```suggestion
# Unit tests (strongly recommended)
./mvnw test
# Check for compilation errors in affected modules
./mvnw clean package -pl <affected-module> -am
```
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo merged PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2758916432
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
+
+## Repository Structure
+
+```text
+seatunnel/
+├── seatunnel-api/ # Core API definitions
+├── seatunnel-connectors-v2/ # Source & Sink connectors (main contribution area)
+├── seatunnel-transforms-v2/ # Transform plugins (including LLM)
+├── seatunnel-engine/ # Zeta engine & Web UI
+├── seatunnel-core/ # Job submission & CLI entry points
+├── seatunnel-translation/ # Flink & Spark adapters
+├── seatunnel-formats/ # Data formats (JSON, Avro, etc.)
+├── seatunnel-e2e/ # End-to-End integration tests
+├── docs/ # Documentation (en & zh)
+└── config/ # Default configurations
+```
+
+## Code Standards
+
+### Java Backend
+
+* **Formatting**: Google Java Format (AOSP style), enforced by Spotless
+* **Imports**:
+ * No wildcard imports
+ * Use shaded dependencies: `org.apache.seatunnel.shade.*`
+* **Nullability**: Avoid implicit null assumptions
+* **Visibility**: Keep APIs minimal; prefer package-private when possible
+* **Comments**: Add comments for important methods (public APIs, complex logic).
+
+### Apache License Header (MANDATORY)
+
+All **new files** MUST include the ASF license header:
+
+```java
+/*
+ * 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.
+ */
+```
+
+## 🚨 Backward Compatibility (VERY IMPORTANT)
+
+Agents MUST treat backward compatibility as a **hard constraint**.
+
+* DO NOT remove or rename existing config options
+* DO NOT change default values casually
+* DO NOT break public APIs or SPI contracts
+
+Any incompatible change MUST:
+
+* Be explicitly documented
+* Be documented in `docs/en/introduction/concepts/incompatible-changes.md`
+* Include migration guidance
+* Be clearly explained in the PR description
+
+## Dependency Rules
+
+* DO NOT introduce new dependencies unless absolutely necessary
+* Prefer existing shaded dependencies under `org.apache.seatunnel.shade.*`
+* Any new dependency MUST:
+ * Be justified in the PR description
+ * Consider shading, size, and conflict risks
+
+## Architecture Guidelines
+
+### Connector (V2)
+
+* Implement `SeaTunnelSource` or `SeaTunnelSink`
+* Define configs using `Option`
+* Support parallelism via `SourceSplitEnumerator`
+* Avoid connector-specific logic leaking into engine or core
+
+### Zeta Engine
+
+* **Client**: Submits job config
+* **Master**: Schedules & coordinates
+* **Worker**: Executes tasks (Source → Transform → Sink)
+
+Respect task boundaries and lifecycle semantics.
+
+## Configuration (Option) Rules
+
+* All user-facing configs MUST be defined using `Option`
+* Each option MUST include:
+ * name
+ * type
+ * default value (if applicable)
+ * clear description
+* Option names are **stable contracts** and must not be renamed lightly
+
+## Error Handling & Logging
+
+* Exceptions MUST include sufficient context (table, task, config key)
+* Avoid swallowing exceptions
+* Use proper log levels:
+ * INFO – lifecycle events
+ * WARN – recoverable issues
+ * ERROR – task-failing errors
+* NEVER log sensitive information (passwords, tokens, credentials)
+
+## Documentation Rules
+
+* Any user-visible change MUST update:
+
+ * `docs/en`
+ * `docs/zh`
+* Config names, defaults, and examples MUST match the code exactly
+* Documentation is part of the feature, not an afterthought
+
+## Testing Guidelines
+
+### Unit Tests
+
+* Located under `src/test/java`
+* Validate behavior, not implementation details
+* Prefer deterministic and minimal tests
+
+Command:
+
+```bash
+./mvnw test
+```
+
+### E2E Tests
+
+* Located in `seatunnel-e2e`
+* Uses Testcontainers
+* Extend `TestSuiteBase`
+
+Command:
+
+```bash
+./mvnw -DskipUT -DskipIT=false verify
+```
Review Comment:
```bash
# Run specific connector E2E tests
./mvnw test -pl seatunnel-e2e/seatunnel-connector-v2-e2e/connector-xxx-e2e
# Run all E2E tests (warning: time-consuming)
./mvnw -DskipUT -DskipIT=false verify
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "zhangshenghang (via GitHub)" <gi...@apache.org>.
zhangshenghang commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2739322098
##########
AGENTS.md:
##########
@@ -0,0 +1,237 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
+
+## Repository Structure
+
+```text
+seatunnel/
+├── seatunnel-api/ # Core API definitions
+├── seatunnel-connectors-v2/ # Source & Sink connectors (main contribution area)
+├── seatunnel-transforms-v2/ # Transform plugins (including LLM)
+├── seatunnel-engine/ # Zeta engine & Web UI
+├── seatunnel-core/ # Job submission & CLI entry points
+├── seatunnel-translation/ # Flink & Spark adapters
+├── seatunnel-formats/ # Data formats (JSON, Avro, etc.)
+├── seatunnel-e2e/ # End-to-End integration tests
+├── docs/ # Documentation (en & zh)
+└── config/ # Default configurations
+```
+
+## Code Standards
+
+### Java Backend
+
+* **Formatting**: Google Java Format (AOSP style), enforced by Spotless
+* **Imports**:
+ * No wildcard imports
+ * Use shaded dependencies: `org.apache.seatunnel.shade.*`
+* **Nullability**: Avoid implicit null assumptions
+* **Visibility**: Keep APIs minimal; prefer package-private when possible
+
+### Apache License Header (MANDATORY)
+
+All **new files** MUST include the ASF license header:
+
+```java
+/*
+ * 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.
+ */
+```
+
+## 🚨 Backward Compatibility (VERY IMPORTANT)
+
+Agents MUST treat backward compatibility as a **hard constraint**.
+
+* DO NOT remove or rename existing config options
+* DO NOT change default values casually
+* DO NOT break public APIs or SPI contracts
+
+Any incompatible change MUST:
+
+* Be explicitly documented
+* Be documented in `docs/en/introduction/concepts/incompatible-changes.md`
+* Include migration guidance
+* Be clearly explained in the PR description
+
+## Dependency Rules
+
+* DO NOT introduce new dependencies unless absolutely necessary
+* Prefer existing shaded dependencies under `org.apache.seatunnel.shade.*`
+* Any new dependency MUST:
+ * Be justified in the PR description
+ * Consider shading, size, and conflict risks
+
+## Architecture Guidelines
+
+### Connector (V2)
+
+* Implement `SeaTunnelSource` or `SeaTunnelSink`
+* Define configs using `Option`
+* Support parallelism via `SourceSplitEnumerator`
+* Avoid connector-specific logic leaking into engine or core
+
+### Zeta Engine
+
+* **Client**: Submits job config
+* **Master**: Schedules & coordinates
+* **Worker**: Executes tasks (Source → Transform → Sink)
+
+Respect task boundaries and lifecycle semantics.
+
+## Configuration (Option) Rules
+
+* All user-facing configs MUST be defined using `Option`
+* Each option MUST include:
+ * name
+ * type
+ * default value (if applicable)
+ * clear description
+* Option names are **stable contracts** and must not be renamed lightly
+
+## Error Handling & Logging
+
+* Exceptions MUST include sufficient context (table, task, config key)
+* Avoid swallowing exceptions
+* Use proper log levels:
+ * INFO – lifecycle events
+ * WARN – recoverable issues
+ * ERROR – task-failing errors
+* NEVER log sensitive information (passwords, tokens, credentials)
+
+## Documentation Rules
+
+* Any user-visible change MUST update:
+
+ * `docs/en`
+ * `docs/zh`
+* Config names, defaults, and examples MUST match the code exactly
+* Documentation is part of the feature, not an afterthought
+
+## Testing Guidelines
+
+### Unit Tests
+
+* Located under `src/test/java`
+* Validate behavior, not implementation details
+* Prefer deterministic and minimal tests
+
+Command:
+
+```bash
+./mvnw test
+```
+
+### E2E Tests
+
+* Located in `seatunnel-e2e`
+* Uses Testcontainers
+* Extend `TestSuiteBase`
+
+Command:
+
+```bash
+./mvnw -DskipUT -DskipIT=false verify
+```
+
+## Performance Awareness
+
+Agents MUST consider performance implications:
+
+* Avoid unnecessary object creation in hot paths
+* Be cautious with large in-memory buffers
+* Consider parallelism and resource usage
+
+## PR Scope Rule
+
+* Keep changes minimal and focused
+* Avoid unrelated refactors or formatting-only changes
+* One PR should solve **one problem**
+
+## Running & Debugging
+
+### Build from Source
+
+```bash
+./mvnw clean install -DskipTests -Dskip.spotless=true
+```
+
+### Install Connectors
+
+```bash
+sh bin/install-plugin.sh 2.3.13
Review Comment:
Do not hardcode the version number
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "corgy-w (via GitHub)" <gi...@apache.org>.
corgy-w commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3815717907
> Isn’t Chinese documentation in the plan?
@chl-wxp I took a look at the loading logic of commonly used tools. It's all unnecessary to load Chinese items like AGENT/GPT in the root directory
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2744359307
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
Review Comment:
A small detail: the document states the strict format is [Type][Module], but the example has [Docs] ... (no Module). Let's standardize this part.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on code in PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#discussion_r2759012043
##########
AGENTS.md:
##########
@@ -0,0 +1,238 @@
+# LLM Context Guide for Apache SeaTunnel
+
+This guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.
+
+## ⚠️ CRITICAL: Validate Before Proposing Changes
+
+**Agents MUST run verification commands locally before suggesting or finalizing changes.**
+
+```bash
+# Format code (mandatory)
+./mvnw spotless:apply
+
+# Quick verification (mandatory)
+./mvnw -q -DskipTests verify
+
+# Unit tests (strongly recommended)
+./mvnw test
+```
+
+Failure to meet these requirements will likely result in PR rejection.
+
+## Git Commit Message Convention
+
+SeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.
+
+**Format**:
+
+```
+[Type][Module] Description
+```
+
+### Types
+
+* `Feature` – New features
+* `Fix` – Bug fixes
+* `Improve` – Improvements to existing behavior
+* `Docs` – Documentation-only changes
+* `Test` – Test cases or test framework changes
+* `Chore` – Build, dependency, or maintenance tasks
+
+### Modules
+
+* `Connector-V2` – seatunnel-connectors-v2
+* `Zeta` – seatunnel-engine (Zeta engine)
+* `Core` – seatunnel-core
+* `API` – seatunnel-api
+* `Transform-V2` – seatunnel-transforms-v2
+* `Format` – seatunnel-formats
+* `Translation` – seatunnel-translation
+* `E2E` – seatunnel-e2e
+
+### Examples
+
+* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`
+* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`
+* `[Feature][Transform-V2] Add LLM transform plugin`
+* `[Improve][Core] Optimize jar package loading speed`
+* `[Docs] Update quick start guide`
+
+## Repository Structure
+
+```text
+seatunnel/
+├── seatunnel-api/ # Core API definitions
+├── seatunnel-connectors-v2/ # Source & Sink connectors (main contribution area)
+├── seatunnel-transforms-v2/ # Transform plugins (including LLM)
+├── seatunnel-engine/ # Zeta engine & Web UI
+├── seatunnel-core/ # Job submission & CLI entry points
+├── seatunnel-translation/ # Flink & Spark adapters
+├── seatunnel-formats/ # Data formats (JSON, Avro, etc.)
+├── seatunnel-e2e/ # End-to-End integration tests
+├── docs/ # Documentation (en & zh)
+└── config/ # Default configurations
+```
+
+## Code Standards
+
+### Java Backend
+
+* **Formatting**: Google Java Format (AOSP style), enforced by Spotless
+* **Imports**:
+ * No wildcard imports
+ * Use shaded dependencies: `org.apache.seatunnel.shade.*`
+* **Nullability**: Avoid implicit null assumptions
+* **Visibility**: Keep APIs minimal; prefer package-private when possible
+* **Comments**: Add comments for important methods (public APIs, complex logic).
Review Comment:
**Line 86** mentions adding comments for "important methods" but doesn't clarify what makes a method "important" or provide examples.
**Suggested clarification:**
```java
/**
* Enumerates source splits for parallel reading.
* Called once during job initialization.
*
* @param context Split enumeration context
* @return Collection of discovered splits
*/
@Override
public List<SourceSplit> enumerateSplits(SplitEnumerationContext context) {
// Implementation
}
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add LLM contribution guide [seatunnel]
Posted by "davidzollo (via GitHub)" <gi...@apache.org>.
davidzollo commented on PR #10411:
URL: https://github.com/apache/seatunnel/pull/10411#issuecomment-3841221889
**Suggested addition**
```markdown
## Adding a New Connector
When contributing a new connector, you MUST update:
1. `plugin-mapping.properties` - Add connector mapping
2. `seatunnel-dist/pom.xml` - Include in distribution
3. `seatunnel-e2e/` - Add E2E test cases
4. `config/plugin_config` - Add plugin configuration
5. `docs/en/connector-v2/` - Add English documentation
6. `docs/zh/connector-v2/` - Add Chinese documentation
```
**Suggested new section:**
```markdown
## Common Pitfalls to Avoid
1. **Don't use wildcard imports** - Spotless will fail
2. **Don't forget license headers** - All new files need ASF headers
3. **Don't skip `-nsu` flag** - Ensures build reproducibility
4. **Don't modify existing Option names** - Breaking change for users
5. **Don't commit without running spotless:apply** - CI will fail
6. **Don't use `System.out.println`** - Use proper logging framework
```
## What Works Well
1. **Clear structure** - Well-organized sections
2. **Good examples** - Commit message format examples are helpful
3. **Backward compatibility emphasis** - Critical for production systems
4. **Repository structure** - Accurate and helpful
5. **License header template** - Essential for Apache projects
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org