zhangshenghang opened a new pull request, #12971:
URL: https://github.com/apache/seatunnel/pull/12971
## Purpose of this PR
Yes — this contribution acknowledges it is made to the **Apache SeaTunnel**
project.
This PR fixes a batch of real documentation defects found by auditing docs
(both `docs/en` and `docs/zh`) against the actual source code on `dev`. Every
fix below was verified against the Java/Shell/YAML sources quoted.
## What documentation issues were found
**Engine / job configuration (highest impact — several documented keys, CLI
flags and class names do not exist):**
- `state-storage-and-recovery.md` (en+zh): documented non-existent
checkpoint keys `max-concurrent` / `tolerable-failure`; non-existent CLI flag
`--stop-job` (real flag is `-s/--savepoint <jobId>`); wrong IMap names
(`running-job-state` etc. → real `engine_runningJobState`,
`engine_runningJobInfo`, ...); fabricated MapStore config (`initial-load-mode`,
`hazelcast.fs.*` properties → real `initial-mode` + `FileMapStore` +
`namespace`/`clusterName`/`businessName`); fabricated WAL directory layout and
compaction knobs. Rewritten against `CheckpointConfig`, `ServerConfigOptions`,
`Constant`, `FileMapStore`, `IMapFileStorage`, `FileConstants`,
`ClientCommandArgs`.
- `tuning-guide.md` (en+zh): wrong log file name (`seatunnel-server.log` →
`seatunnel-engine-server.log`, per `seatunnel-cluster.sh`/`log4j2.properties`)
and references to the fabricated `/tmp/seatunnel/imap` WAL layout (aligned with
the corrected state-storage doc).
- `event-listener.md` (en+zh): event types
`READER_OPEN`/`READER_CLOSE`/`WRITER_OPEN`/`WRITER_CLOSE` do not exist in
`EventType` (replaced with the real `LIFECYCLE_*` constants +
`READER_MESSAGE_DELAYED`); wrong import packages; example handler called
methods that do not exist (`getPluginId`, `getParallelism`, `getRecordCount`,
`getEventTime`, `getAddedColumns`, `getTableName`) — rewritten with real
getters.
- `flink.md` (en+zh): referenced non-existent example module
`seatunnel-examples/seatunnel-flink-connector-v2-example` and class
`org.apache.seatunnel.example.flink.v2.SeaTunnelApiExample` — replaced with the
real modules/classes.
- `config-encryption-decryption.md` (en+zh): `config/v2.batch.template` does
not exist → `config/v2.batch.config.template`.
- `logging.md` (en+zh): `seatunnel.yml` → `seatunnel.yaml`.
- `getting-started/locally/deployment.md` (en+zh):
`plugins-mapping.properties` → `plugin-mapping.properties`.
**Connector option tables (doc ↔ code mismatches):**
- `S3-Redshift.md` (en+zh): option `access_secret` does not exist in code
(real key `secret_key`); added required `fs.s3a.endpoint` and
`fs.s3a.aws.credentials.provider` rows (a job configured per the old doc fails
at runtime).
- `ObsFile.md` source (en+zh): removed the "OBS STS" section built around
the non-existent `hadoop_obs_properties` option; added `xml`/`binary` to the
supported-format checklist (code supports both); fixed broken `sheet_name`
description.
- `Persistiq.md` (en+zh): `format` default documented as `json`, code
default is `TEXT` (inherited `HttpSourceOptions.FORMAT`, no override).
- `Notion.md` (en+zh): example configured
`page_type`/`cursor_field`/`cursor_response_field` at top level, but
`HttpSource` only reads them inside the `pageing` block — the old example
silently did not enable pagination; fixed table keys (`pageing.*`) and nested
the example config.
- `SelectDB-Cloud.md` (en+zh): `selectdb.config` marked required but is
`optional(...)` in the factory.
- `Snowflake.md` (en+zh): `generate_sink_sql` referenced throughout but
missing from the options table — added (boolean, default false).
- `Oracle-CDC.md` (en+zh): `url` was marked unconditionally required; per
the factory `hostname`+`port` (bundled) may replace it — added
`hostname`/`port` rows and made `url` conditionally required.
- `PostgreSQL-CDC.md` (en+zh): `server-time-zone` default documented as
`UTC`, code default is the JVM system time zone.
- `HugeGraph.md` sink (en+zh): documented the multi-table `sourceTable`
mapping key (functional, produces user-facing errors, but was undocumented).
- Missing options added to file-connector docs to match the factories'
`optionRule()`: `excel_use_header_line`
(S3File/OssFile/OssJindoFile/GcsFile/BosFile/SftpFile/FtpFile sources),
`enable_header_write` (OssJindoFile/BosFile/CosFile sinks), `tables_configs`
(OssFile/SftpFile sources), `null_format` (BosFile source),
`date_format`/`datetime_format`/`time_format`/`metalake_type` (GcsFile source).
- Type-column accuracy: `format` labeled `String` where code declares
`enumType` changed to `enum` (AmazonSqs sink+source, RocketMQ sink, Rabbitmq
source, WebSocket source, Persistiq source).
**Transforms:**
- `calcite.md` (en+zh): added the `GET_JSON_OBJECT` built-in UDF (registered
via `GetJsonObjectFunction`, already cross-referenced by `sql-functions.md`).
- `embedding.md` (en+zh): added `process_batch_size` (int, default 100,
fallback key `inference_batch_size`) present in the factory rule.
## Which areas/files were updated
70 files (355 insertions / 319 deletions), always in matched en/zh pairs,
under:
- `docs/{en,zh}/engines/**`, `docs/{en,zh}/introduction/configuration/`,
`docs/{en,zh}/getting-started/locally/`
- `docs/{en,zh}/connectors/{source,sink}/**` (S3-Redshift, ObsFile, S3File,
OssFile, OssJindoFile, GcsFile, BosFile, CosFile, FtpFile, SftpFile, Persistiq,
Notion, FacebookAds, GoogleAds, SelectDB-Cloud, Snowflake, HugeGraph,
Oracle-CDC, PostgreSQL-CDC, AmazonSqs, RocketMQ, Rabbitmq, WebSocket)
- `docs/{en,zh}/transforms/{calcite,embedding}.md`
## Whether English and Chinese docs were both checked
Yes. Every issue above was fixed in both `docs/en` and `docs/zh` (or
confirmed to only exist in one language).
## How duplicate PRs from the last 7 days were checked
Searched all PRs created since 2026-10-16 (`gh pr list --search
"created:>=2026-10-16"`). Recent doc PRs by the same author — #12951, #12941,
#12932, #12911, #12865 — plus #12859 (Copy transform), #12965 (IRIS link),
#12856 (OpenAPI contract) were reviewed file-by-file, and this PR avoids every
file they touch. The one real overlap found (duplicate `sheet_name` row in
`docs/zh/connectors/source/ObsFile.md`, already fixed by open PR #12911) was
intentionally reverted from this PR.
## How the change was verified
- Every doc claim was checked against the source (Options classes, Factory
`optionRule()`, `ClientCommandArgs`, `CheckpointConfig`/`ServerConfigOptions`,
`FileMapStore`/`IMapFileStorage`, `EventType`/event classes, shell scripts and
shipped configs), with file:line evidence.
- Automated checks over all 70 changed files: markdown table structure
(column-count consistency) and relative link targets — all pass.
- The full docusaurus website build was not run locally (it requires
checking out the separate `apache/seatunnel-website` repo and a full npm
install, per the `document` CI job); the CI `Build website` job will validate
rendering.
--
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]
