zhangshenghang opened a new pull request, #13204:
URL: https://github.com/apache/seatunnel/pull/13204
Yes — this is a contribution to **Apache SeaTunnel**.
### Purpose of this pull request
This PR fixes documentation that contradicts the current source code on
`dev`: Java API snippets on the architecture pages, connector examples that
cannot run, wrong option statements, and stale CLI/version details. English and
Chinese pages were checked together and fixed together wherever both had the
problem. Every change was checked against the code referenced below.
There is no tracking issue. This is a documentation-only correctness fix.
### What documentation issues were found and what was changed
**1. Architecture API pages show APIs that do not exist
(`architecture/api-design`)**
- `sink-architecture.md` (en, zh)
- `SinkCommitter` and `SinkAggregatedCommitter` were shown as `extends
Closeable`. In the code they `extend Serializable`.
- Both `abort(...)` methods were shown as optional `default` no-ops. In
the code they are abstract (`SinkAggregatedCommitter#abort` throws
`Exception`), so implementers must write them.
- `SinkCommitter#close()` was shown but does not exist.
- `restoreCommit(...)` was shown as a `void` no-op. Its real default calls
`commit(...)` again.
- `init()` was missing.
- `SinkWriter#prepareCommit(long)` and `snapshotState(long)` were shown as
abstract. In the code they are defaults, and the deprecated no-arg
`prepareCommit()` is the abstract method.
- The page said the committer "runs on master". This contradicts section
2.2 of the same page and `SinkFlowLifeCycle#notifyCheckpointComplete`, which
runs it in the worker-side sink task.
- The page said `abortPrepare()` is "only used by Spark".
`SinkFlowLifeCycle#abortPreparedWriter` also calls it on the SeaTunnel Engine.
- The zh page called `abort` "(optional)".
- The example committers now implement the abstract methods.
- `source-architecture.md` (en)
- The `SeaTunnelSource` parent interfaces were incomplete:
`PluginIdentifierInterface` (which requires `getPluginName()`),
`SeaTunnelPluginLifeCycle` and `SeaTunnelJobAware` were missing.
- `getSplitSerializer()` and `getEnumeratorStateSerializer()` were shown
as abstract. They are defaults that return `DefaultSerializer`.
- `catalog-table.md` (en, zh)
- The page taught a `DataTypes.TINYINT()/VARCHAR(n)/ROW(...)` factory that
does not exist anywhere in SeaTunnel. All snippets now use the real types:
`BasicType`, `DecimalType`, `LocalTimeType`, `PrimitiveByteArrayType`,
`ArrayType.of`, `MapType`, `SeaTunnelRowType`.
- `Column.builder()` does not exist (`Column` is abstract). Replaced with
`PhysicalColumn.builder()`.
- `TableSchema.Builder#column(String, type)`, `primaryKey(String)` and
`constraint(...)` do not exist. Replaced with `column(Column)`,
`primaryKey(PrimaryKey)` and `constraintKey(...)`.
- `SchemaChangeEvent` is an interface extending `Event`, not an abstract
class with a `tableId` field. `AlterTableAddColumnEvent` has no two-argument
constructor; the snippets now use the `add(...)` factories.
- The schema-override example used a `JDBC` block with `schema { fields
}`. `Jdbc` derives its schema from metadata, and its `schema` option is the
database schema name. The example now uses Kafka.
- The `schema-evolution { enabled, auto-add-column, ... }` block does not
exist. It is replaced with the real `schema-changes.enabled` (CDC source) plus
`schema_save_mode`, matching what the zh page already said.
- `translation-layer.md` (en, zh)
- Flink adapters:
- `FlinkSource` and `FlinkSourceReader` produce `SeaTunnelRow` and have
no `<T>` type parameter.
- `EnumeratorStateWrapper`, `CollectorAdapter` and
`SplitWrapper#getSplit` do not exist. The real names are `EnumStateT`,
`FlinkRowCollector` and `getSourceSplit()`.
- The split serializer is `SplitWrapperSerializer`.
- The enumerator `start()` only calls `open()`. `run()` is called from
`addReader()` (via `registerReader`, not `addReader`) after all readers
register.
- `sendSplitRequest()` forwards to Flink; it is not a no-op.
- `FlinkSink`/`FlinkSinkWriter` use `CommitWrapper`/`FlinkWriterState`,
with `CommitWrapperSerializer`/`FlinkWriterStateSerializer`.
- Spark adapters:
- `SparkSource`, `SparkInputPartition`, `SparkPartitionReader`,
`SparkCommitMessage` and `SparkTypeConverter` do not exist. The real classes
are now used: `BatchSourceReader`, `BatchPartition`,
`SeaTunnelInputPartitionReader`, `SparkDataSourceWriter`,
`SparkWriterCommitMessage` and `TypeConverterUtils`.
- Splits are not enumerated on the driver. There is one virtual
partition per subtask, running `ParallelSource`/`CoordinatedSource`.
- The driver-side commit goes through `SinkAggregatedCommitter`.
- `FlinkSimpleVersionedSerializer#getVersion()` returns `0`; SeaTunnel's
`Serializer` has no `getVersion()`.
- The zh prose had the same wrong statements and is fixed too.
**2. Connector docs**
- `sink/SensorsData.md` (en, zh)
- The *Item Tracking* example did not set `entity_name = items`. With the
default `users`, `record_type = items` throws `UNSUPPORTED_RECORD_TYPE` in
`SensorsDataRecordBuilder`. The example now uses only the options item records
use.
- The *Console Output* example missed `identity_fields`. With the default
`entity_name = users` it is conditionally required
(`SensorsDataBaseOptionRules`), so validation fails.
- `source/GoogleBigtable.md` (en, zh): the options table had no `schema`
row. The source calls `CatalogTableUtil.buildWithConfig`, which fails with
`Schema config need option [schema]` when it is missing. Added the row and a
`schema [config]` section.
- `source/Phoenix.md` (en, zh): the docs said the SELECT order "must match
`schema.fields`". The JDBC source has no such option; the schema is derived
from the query.
- `source/Vertica.md` (en, zh): the docs said `partition_column` was
"numeric only". `ChunkSplitter#isSupportSplitColumn` and `FixedChunkSplitter`
also support STRING and DATE.
**3. Developer, deployment and getting-started docs**
- `developer/setup.md` (en, zh): the docs required Scala 2.11.12. The build
uses `scala.version` 2.12.15.
- `developer/coding-guide.md` (en, zh): the example threw a nonexistent
`SeaTunnelORCFormatException` without `new`. It now uses
`FileConnectorException` with `FileConnectorErrorCode.FILE_READ_FAILED`.
- `getting-started/application/kubernetes/configuration.md`, `faq.md` (en,
zh): the docs warned against passing `kubernetes.kubeconfig` with `-i`.
`ApplicationCommandArgs` has no `-i`; overrides use `-D`, as the same page's
caution box already says.
- `getting-started/kubernetes/configuration.md` (en, zh): the IMap
`storage.type` list missed `gcs` (`FileConfiguration` has HDFS/S3/OSS/GCS).
- `getting-started/locally/quick-start-flink.md`, `quick-start-spark.md`
(en, zh): the sample output (`fields : name, age` / `row=1 : ...`) is not
printed by any current code.
- It is replaced with the `ConsoleSinkWriter` format (`output rowType:
...`, `subtaskIndex=... rowIndex=...`).
- `FieldMapper` emits fields in `field_mapper` order (`age`, then
`new_name`). I confirmed the key order is preserved with a small run against
`ReadonlyConfig`, which returns `LinkedHashMap {age=age, name=new_name}`.
### Which areas/files were updated
29 files, documentation only: `docs/en` + `docs/zh` under
`architecture/api-design`, `connectors/source`, `connectors/sink`, `developer`,
`getting-started/application/kubernetes`, `getting-started/kubernetes`,
`getting-started/locally`. No code, config option, default value or API changed.
### Whether English and Chinese docs were both checked
Yes. Every page was checked in both languages, and both were fixed where
both had the problem. `source-architecture.md` is changed in en only, because
the zh page has no code snippet and its statements are accurate.
### How duplicate PRs from the last 7 days were checked
- Listed every PR created since 2026-11-03 (63 PRs) with `gh pr list
--search "created:>=2026-11-03"` and compared their changed files with this PR.
No overlap remains.
- One fix (zh `local-mode-deployment.md` `-e local` → `-m local`) was
dropped because #13149 already contains it.
- Also compared against all 368 open PRs, including older ones. The
Cloudberry `timer flush` and MySQL `partition_column` fixes were dropped
because #11782 already proposes them.
- Other open PRs touch different lines of the same files: #11704, #11713,
#12943, #13015, #12328, #11174, #10874. None makes the same fix.
- The zh Windows `cd apache-seatunnel-3.0.0` mismatch is already fixed in
#13193, so it is not repeated here.
### Does this PR introduce any user-facing change?
Yes, documentation only. The docs now match the current behaviour; nothing
in the product changes.
### How was this patch tested?
- Relative link and anchor check over all `docs/en` and `docs/zh` pages: no
new broken links. This includes the new `#schema-mapping` / `#schema-映射`
anchors.
- `markdown-link-check -c .dlc.json` (the CI dead-link tool) on all 29
changed files: no dead links.
- A scan of the newly added text for MDX-unsafe `<tag` / `{...}` outside
code: none introduced.
- `./mvnw spotless:check`: passed. Markdown formatting is disabled in the
Spotless config, so it does not cover these files.
- Every changed statement and snippet was checked against the cited classes
on current `dev`. The `FieldMapper` key order was confirmed with a small Java
program run against the built `seatunnel-api` classes.
- Not run: the full Docusaurus website build. It needs the separate
`seatunnel-website` repository, and the PR CI `Build website` job covers it.
### Check list
- [x] Documentation in both `docs/en` and `docs/zh` updated where applicable.
- [x] No incompatible changes.
--
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]