davidzollo opened a new issue, #10533:
URL: https://github.com/apache/seatunnel/issues/10533
## Summary
SeaTunnel's core runtime code is impressively engineered, but most key
methods across the **Zeta engine**, **Connector V2 API SPI**, and the
**multi-table sink framework** currently have no Javadoc comments. This makes
the learning curve steep for new contributors who want to understand how the
system works end-to-end.
This issue proposes adding concise Javadoc to the most important lifecycle
and coordination methods across these areas, as a contributor-friendly
improvement task.
---
## Motivation
When studying the source code (e.g., while implementing a new connector or
debugging a Zeta job), contributors must infer the contract and intent of key
methods purely from implementation. For example:
- `CheckpointCoordinator.java` (1174 lines) has ~21 Javadoc comment lines
(~1.8%)
- `TaskExecutionService.java` (1018 lines) has ~24 Javadoc comment lines
(~2.4%)
- `CoordinatorService.java` (1177 lines) has ~50 Javadoc comment lines
(~4.3%)
- `MultiTableSinkWriter.java` (373 lines) has **zero** method-level Javadoc
Methods like `initResourceManager`, `checkQueueRemain`, `snapshotState`,
`prepareCommit`, `triggerCheckpoint`, `restoreComplete` carry important
lifecycle semantics that are not obvious without reading through hundreds of
lines of context.
---
## Suggested scope (good first issue — pick any area)
Contributors can pick one file or one area. Suggested priority areas:
### 1. Connector V2 API SPI (`seatunnel-api`)
| File | Key methods to document |
|------|------------------------|
| `SeaTunnelSource.java` | `createReader`, `getProducedType`,
`getBoundedness` |
| `SourceSplitEnumerator.java` | `open`, `run`, `addSplitsBack`,
`handleSplitRequest`, `snapshotState` |
| `SinkWriter.java` | `write`, `prepareCommit`, `snapshotState`,
`abortPrepare`, `close` |
| `SupportMultiTableSinkWriter.java` | `initMultiTableResourceManager`,
`setMultiTableResourceManager`, `primaryKey` |
| `MultiTableResourceManager.java` | `getSharedResource`, `close` |
### 2. Multi-table sink framework (`seatunnel-api`)
| File | Key methods to document |
|------|------------------------|
| `MultiTableSinkWriter.java` | Constructor, `initResourceManager`, `write`,
`prepareCommit`, `snapshotState`, `checkQueueRemain`, `close` |
| `MultiTableWriterRunnable.java` | `run`, queue-draining logic |
### 3. Zeta Engine Server (`seatunnel-engine`)
| File | Key methods to document |
|------|------------------------|
| `CoordinatorService.java` | `submitJob`, `cancelJob`, `getJobStatus`,
master/worker registration |
| `TaskExecutionService.java` | `submitTask`, `cancelTask`, task state
transitions |
| `CheckpointCoordinator.java` | `triggerCheckpoint`, `acknowledgeTask`,
`restoreComplete`, barrier injection |
---
## Comment style guide
Follow the existing project convention (also documented in `CLAUDE.md`):
```java
/**
* Enumerates source splits for parallel reading.
* Called once during job initialization after {@link #open()}.
*
* <p>Implementations should avoid blocking here; long-running enumeration
* should be done in {@link #run()}.
*
* @param context enumeration context providing access to assigned readers
*/
void run() throws Exception;
```
Guidelines:
- Describe **what** the method does and **when** it is called in the
lifecycle
- Note thread-safety guarantees if relevant
- Note side effects (state mutation, blocking calls)
- Reference related methods where helpful
- Keep comments concise — 2–5 lines per method is sufficient
- No need to repeat parameter types (already in the signature)
---
## How to contribute
1. Pick one file from the scope above (comment on this issue to claim it)
2. Add Javadoc to the key public/package-private methods in that file
3. Run `./mvnw spotless:apply` to ensure formatting
4. Open a PR with title format: `[Docs][Core] Add Javadoc to <ClassName>`
This is a **good first issue** — no logic changes required, just reading and
writing clear comments. It is also a great way to deepen your understanding of
how SeaTunnel works internally.
---
## References
- SeaTunnel Connector V2 developer guide:
https://seatunnel.apache.org/docs/contribution/contribute-transform-v2-guide
- SeaTunnel architecture overview:
https://seatunnel.apache.org/docs/concept/schema-feature
--
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]
