zhangshenghang opened a new pull request, #12641:
URL: https://github.com/apache/seatunnel/pull/12641
## What documentation issues were found
While auditing the Zeta engine documentation (`docs/en/engines/**` and
`docs/zh/engines/**`) against the current `dev` source code, I found the
following verified issues:
### Config keys / YAML structure that do not match the parser
- `engine-jar-storage-mode.md` (EN+ZH): documents the enable key as
`connector-jar-storage-enable`, but the parser only accepts `enable` under
`jar-storage` (`ServerConfigOptions.ENABLE_CONNECTOR_JAR_STORAGE`,
`YamlSeaTunnelDomConfigProcessor.parseConnectorJarStorageConfig`). The YAML
examples were also missing the required `seatunnel: engine:` nesting, so a
copy-pasted example is silently ignored.
- `hybrid-cluster-deployment.md` / `separated-cluster-deployment.md`
(EN+ZH): the `coordinator-service` examples were top-level; the parser only
reads `coordinator-service` inside `seatunnel.engine`.
- `tuning-guide.md` (EN+ZH): the three S3 checkpoint mitigation examples
omitted `storage.type: s3` in `plugin-config`, so `HdfsStorage` falls back to
the `local` storage type and every `fs.s3a.*` / `s3.bucket` key is ignored;
they now set `storage.type: s3` explicitly.
- `checkpoint-storage.md` (EN+ZH): used `//` inline comments inside YAML
blocks (invalid YAML); replaced with `#`.
- `tuning-guide.md`: five references to the retired log name
`seatunnel-server.log` corrected to `seatunnel-engine-server.log` (the name set
by `seatunnel-cluster.sh` via `-Dseatunnel.logs.file_name`).
- `tcp.md` (EN+ZH): claimed Hazelcast auto-increments member ports 5701,
5702, ...; SeaTunnel's shipped `hazelcast.yaml` sets `port: 5801` with
`port-auto-increment: false`.
- `security.md` (EN+ZH): `enable-http` default documented as `true`; the
code default is `false` (`ServerConfigOptions.ENABLE_HTTP`).
- `tuning-guide.md`: referenced a nonexistent `write-behind-delay-seconds`
key (Hazelcast uses `write-delay-seconds`), and claimed checkpoint intervals
default to 10s (code default is 300000 ms; only the shipped template sets
10000).
### REST API response shapes that do not match the server
- `rest-api-v1.md` / `rest-api-v2.md` (EN+ZH): `/overview` example returned
`"works"`; the field is `workers` (`OverviewInfo`, asserted by `RestApiIT`).
- Same files: `finishedTime` corrected to `finishTime`
(`RestConstant.FINISH_TIME`) in 8 example/notes places; `/stop-job` response
corrected to a string `jobId` (`JobInfoService.stopJob`); lowercase
`sourceReceivedCount`/`sinkWriteCount` corrected to
`SourceReceivedCount`/`SinkWriteCount` (`MetricNames`); the deprecated
`/running-job/:jobId` examples completed with the `SinkCommitted*` /
`IntermediateQueueSize` keys the endpoint actually returns; `startTime` (always
returned by `BaseService`) added to the job examples and the always-returned
field list.
- v1 `option-rules` `type` parameter now also lists `transform`
(`OptionRulesService` registers SOURCE, SINK and TRANSFORM); v1 `submit-job` /
`submit-jobs` parameter tables now include `format`, `restoreMode`,
`restoreSourceJobId`, which v1 accepts exactly like v2.
### Documented features that do not exist in code
- `rest-api-job-lifecycle.md` (EN+ZH): removed the claim that
`/job-info/:jobId` returns a `savepointPath` field (no such field is emitted),
and replaced section 6.3, which documented nonexistent `restore.mode` /
`savepoint.path` env options, with a note that restore source selection is only
via `restoreMode`/`restoreSourceJobId` (`RestoreMode` enum).
### CLI and engine docs
- `user-command.md` (EN+ZH): the `-h` output block was missing six real
options (`--set-job-id`, `--checkpoint-overview`, `--checkpoint-history`,
`--checkpoint-history-pipeline`, `--checkpoint-history-limit`,
`--checkpoint-history-status`); the intro claimed the CLI can delete jobs,
which no CLI/REST delete operation supports.
- `usage.mdx` (EN+ZH): added the shipped Flink 1.20 entry point
(`start-seatunnel-flink-20-connector-v2.sh`) to the entrypoint/options/example
tabs.
- `flink.md` (EN+ZH): the referenced example module
`seatunnel-examples/seatunnel-flink-connector-v2-example` and class
`org.apache.seatunnel.example.flink.v2.SeaTunnelApiExample` no longer exist;
now points to the real `seatunnel-flink-{13,15,20}-example` modules and
`SeaTunnelBatchJobExample`/`SeaTunnelStreamingJobExample`.
- `overview.md` (EN+ZH): "All SeaTunnel V2 connectors are compatible with
all three engines" contradicted the table below it (CDC is not supported on
Spark).
- `local-mode-deployment.md` (ZH): `-e local` replaced with `-m local`
(`-e/--deploy-mode` is deprecated since 2.3.1); `deployment.md` (ZH): added the
missing "experimental feature" qualifier for separated cluster mode;
`hybrid/separated-cluster-deployment.md` (ZH): restored broken
`job-metrics-partition-count` YAML indentation, fixed `dynamic-slot: ture`
typo, and ported the missing "S3 (Minio) for IMap storage" sections from EN.
### Index gaps and EN/ZH sync
- `docs/sidebars.js`: `engines/zeta/stain-trace`,
`engines/zeta/stain-trace-quickstart`, `engines/zeta/realtime-observability`,
`getting-started/recipes/jdbc-to-jdbc`, and four `introduction/concepts` pages
(`config`, `incompatible-changes`, `metadata-spi`, `gravitino-type-mapping`)
existed on disk (several linked from other docs) but were unreachable from the
navigation; they are now indexed.
- ZH `rest-api-v2.md`: added the missing Field Description table of the
checkpoint-history endpoint; ZH `rest-api-v1.md`: translated two leftover
English section headings.
- `telemetry.md` (EN+ZH): `job_count` label values now include `pending`
(`JobMetricExports`), and the Prometheus scrape section now documents that the
Jetty `/metrics` / `/openmetrics` endpoints on port 8080 (`enable-http`) are
the default source, while the 5801 Hazelcast endpoint additionally requires
`rest-api.enabled: true` (disabled in the shipped template).
## Which areas/files were updated
33 files: `docs/en/engines/**` (15 files), `docs/zh/engines/**` (17 files),
`docs/sidebars.js`. 472 insertions / 203 deletions.
## Were English and Chinese docs both checked?
Yes. Every fix was applied to both language versions where the issue exists
in both; ZH-only gaps (missing Minio checkpoint example, missing S3 IMap
persistence sections, missing `hdfs_site_path`, broken YAML indentation,
deprecated `-e local`) were ported/fixed to bring ZH back in sync with EN.
## Duplicate PR check (last 7 days)
I checked all PRs by this author in the last 7 days before submitting:
#12621, #12615, #12602, #12570 (open) and #12609, #12553, #12499, #12487
(merged). All of them touch `docs/{en,zh}/connectors/**`,
`docs/{en,zh}/transforms/**` or `docs/{en,zh}/connector-v2/**` only; none
touches `docs/{en,zh}/engines/**`, `docs/sidebars.js`, or any file in this PR.
There is no overlap.
## How the change was verified
- Every removed/renamed key, default value, endpoint and JSON field was
checked against the source (grep on `ServerConfigOptions`,
`YamlSeaTunnelDomConfigProcessor`, `RestConstant`, `OverviewInfo`,
`MetricNames`, `BaseService`, `JobInfoService`,
`HdfsConfiguration`/`S3Configuration`/`HdfsStorage`, `FileConfiguration`,
`ClientCommandArgs`, `RestoreMode`, `JobStatus`, `JobMetricExports`,
`JettyService`, `seatunnel-cluster.sh`, `config/hazelcast.yaml`,
`seatunnel-engine-common/src/main/resources/seatunnel.yaml`).
- All 150 `yaml` code fences in the changed files were parsed with a real
YAML parser (0 failures) — this validates the fixed nesting, comments and
storage examples.
- Relative links in all changed files were extracted and resolved (0 broken).
- `docs/sidebars.js` passes `node --check`, and every sidebar id added
resolves to existing files in both `docs/en` and `docs/zh`.
- The full website build (`docusaurus` in the `document` CI job) requires
syncing to the separate apache/seatunnel-website repo and was not run locally
for that reason; the checks above cover the parts of it that are reproducible
from this repository.
--
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]
