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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
