zhangshenghang opened a new pull request, #13097:
URL: https://github.com/apache/seatunnel/pull/13097
## Purpose of the change
This PR closes no specific issue. It is a documentation-only cleanup that
fixes real documentation inaccuracies found by comparing the docs against the
actual source code (branch based on latest `upstream/dev`). I am contributing
to **Apache SeaTunnel** as part of this change.
## What documentation issues were found
**Connector docs (verified against connector source):**
- `RocketMQ` source: `schema` documented as optional with a "read as text"
fallback, but `CatalogTableUtil.buildWithConfig` throws without it, so it is
required for both `json` and `text` formats; `tables_configs` entries
documented as inheriting top-level options, but `RocketMqSourceConfig` parses
each entry from its own map only (no merge) — top-level
`schema`/`format`/`field.delimiter`/`tags` are ignored in multi-table mode.
- `RocketMQ` sink FAQ claimed checkpoint-coordinated 2PC ("prepared during
checkpoint, committed on barrier handshake"), but `RocketMqTransactionSender`
commits the local transaction immediately (`COMMIT_MESSAGE` unconditionally)
and the sink has no committer/checkpoint hook; hash-routing claim qualified to
non-transactional sends.
- `SelectDB-Cloud` sink: `selectdb.config` description was a stale copy of
the `primary_keys` description; rewritten to describe its real role (Copy Into
`data_desc` load properties, `file.type` required).
- `Redshift` sink: `query`/`database` marked `No` for required although
`JdbcSinkFactory.optionRule()` makes `query` required by default
(`generate_sink_sql=false`) and `database` required when
`generate_sink_sql=true`; stale `timer flush` feature checkbox updated to `[x]
(Zeta engine only)` consistent with the JDBC sink.
- `Snowflake` source/sink: `GEOGRAPHY`/`GEOMETRY` mapped to `BYTES` in the
type tables, but `SnowflakeTypeConverter` maps them to `STRING`
unconditionally; removed the fabricated `DECIMAL(p>38) → DECIMAL(38,18)`
read-path row; removed all incorrect `MERGE` upsert claims (Snowflake dialect
`getUpsertStatement` returns `Optional.empty()`, upsert is client-side
insert-or-update).
- `TiDB-CDC`: `column projection` feature checkbox `[ ]` → `[x]`
(`TiDBSource implements SupportColumnProjection`).
- `MySQL-CDC`: `schema-changes.enabled` description said only 4 change types
are supported, but `MySqlIncrementalSource.supports()` also declares
`ALTER_TABLE_COMMENT` and `ALTER_COLUMN_COMMENT`; EN table/FAQ and ZH table/FAQ
updated.
- `OssFile` source: partition example extracted `age=16` from a path
containing `age=26`.
**Data format docs (verified against seatunnel-formats / connector-kafka):**
- `ogg-json.md`: documented `format` value `'-json'` corrected to `ogg_json`
(the real `MessageFormat` enum value).
- `canal-json.md` / `maxwell-json.md` / `ogg-json.md` / `debezium-json.md`:
removed documented-but-nonexistent prefixed keys
(`canal_json.ignore-parse-errors`, `*.database.include`, `*.table.include`,
`debezium-json.ignore-parse-errors`) — no such keys exist and the underlying
unprefixed options are not wired to any connector; replaced with an accurate
note that parse-error behavior is connector-controlled.
- `debezium-json.md`: added the real `debezium_record_include_schema`
(default `true`) and `debezium_record_table_filter` options that the doc's own
examples rely on.
- `kafka-compatible-kafkaconnect-json.md`: added an options table for
`key_converter_schema_enabled` / `value_converter_schema_enabled` (both default
`true`, envelope handling explained).
- `avro.md`: intro said Avro is supported "in kafka connector" only; Pulsar
connectors support it too.
- `canal-json.md`: fixed garbled headline line.
- `format` rows in the four CDC format docs listed default `(none)` although
`KafkaBaseOptions.FORMAT` defaults to `json`.
**Zeta engine docs (verified against seatunnel-engine):**
- `state-storage-and-recovery.md`: removed nonexistent checkpoint options
`max-concurrent` / `tolerable-failure` (replaced with real `min-pause` /
`monitor-history-size`, default interval corrected to 300000 ms); replaced the
fabricated IMap names table (`running-job-state`, `running-pipeline-state`,
...) with the real names from `Constant.java` / `EngineStateStoreNames`
(`engine_runningJobInfo`, `engine_runningJobState`, `engine_finishedJobState`,
`engine_finishedJobMetrics`, `engine_checkpoint-id-map`); replaced the invented
`hazelcast.fs.*` MapStore/WAL configuration, directory layout and tuning knobs
with the real `map.engine*.map-store` + `FileMapStoreFactory` configuration
already documented in the deployment docs.
- `tuning-guide.md`: wrong default checkpoint interval ("every 10s" → 5
minutes), wrong log file name (`seatunnel-server.log` →
`seatunnel-engine-server.log`, the name produced by `seatunnel-cluster.sh`),
and removed references to the nonexistent `write-behind-delay-seconds` knob.
- `rest-api-v1.md`: `/system-monitoring-information` example showed
`isMaster`/`host`/`port` for successful members, but the code only returns
health-metrics tokens for healthy members and `host`/`port` only for
timed-out/failed ones (also aligning with the v2 doc).
- ZH `hybrid-cluster-deployment.md` / `separated-cluster-deployment.md`:
`dynamic-slot: ture` typo → `true`.
## Which areas/files were updated
38 files: 16 connector docs (`docs/{en,zh}/connectors/{source,sink}/...`),
12 data-format docs (`docs/{en,zh}/connectors/formats/...`), 10 Zeta engine
docs (`docs/{en,zh}/engines/zeta/...`). Every fix was applied to both the
English and Chinese page.
## Whether English and Chinese docs were both checked
Yes. All fixes were applied to both language versions. A scripted comparison
of EN/ZH option tables (option names extracted from all connector pages)
reports zero remaining divergence, and the audit confirmed ZH mirrors EN for
every fixed claim.
## How duplicate PRs from the last 7 days were checked
Checked all PRs created since 2026-10-26 (`gh pr list --state all`) and
specifically the doc PRs: merged #13089 (file/Hive/Iceberg/MongoDB/DataHub),
merged #13062 (connector + common options), merged #11779
(PostgreSql/Rabbitmq/Sls/Hudi/Qdrant), open #13072
(Databend/Elasticsearch/Hbase/Maxcompute/ObsFile/FakeSource/Paimon/Pulsar/sink
common options), open #13050
(Clickhouse/Doris/Http/Mysql/Oracle/PostgreSql/Redis/SqlServer/StarRocks/TDengine/DB2/InfluxDB/Milvus/Phoenix/copy/jsonpath/llm),
open #12993 (Cassandra sink/Couchbase/Enterprise-WeChat/Feishu/IoTDB
sink/Lance/Github/Gitlab/MongoDB-CDC/MySQL-CDC/PostgreSQL-CDC/Shopify/Zendesk),
open #12986 (Jdbc/Kafka/Mqtt/sql-functions). None of these touch the files in
this PR except MySQL-CDC.md (#12993 only changes the `server-time-zone` row —
different lines, verified against its diff). Two issues found during the audit
were intentionally skipped because they are already covered by open PRs: the
Cassandra sink `consistency_level` d
escription (fixed in #12993) and the Kafka `ignore_no_leader_partition`
example (file scope of #12986).
## How the change was verified
- All claims above were verified by reading the referenced Java sources
(factories, options classes, dialects, engine config/constants) — file:line
evidence listed inline above.
- Ran scripted checks over the whole docs tree and re-ran them after
editing: internal link resolver (no new broken file links), anchor resolver for
`file.md#anchor` and explicit HTML anchors (0 issues), EN/ZH option-table set
comparison (0 divergence), markdown table column-count check (no broken tables
in changed files), and fenced-code-block balance across all 38 changed files
(OK).
- No Maven build was run: this PR changes only `.md` files, so `./mvnw
verify`/spotless would not exercise any changed content. The structural checks
listed above are the doc-relevant validations.
--
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]
