zhangshenghang opened a new pull request, #13135:
URL: https://github.com/apache/seatunnel/pull/13135
Yes, I am contributing to Apache SeaTunnel.
## What documentation issues were found
While auditing documentation against the actual source code on the current
`dev` branch, I found 19 real doc bugs across the Zeta engine, transform, and
connector docs. Every issue below was verified against a specific code location
before fixing:
**Zeta engine docs**
1. `rest-api-v2.md` (en) documented `scheduleStrategy` values `WAIT` /
`FAIL_FAST`, but `ScheduleStrategy` enum
(`seatunnel-engine-common/.../server/ScheduleStrategy.java`) only has `WAIT`
and `REJECT` — `FAIL_FAST` does not exist in the engine.
2. `rest-api-v2.md` (en + zh) claimed `totalSlot` is always `0` under
`dynamic-slot`. Contradicted by `DefaultSlotService.requestSlot`
(`assignedSlots.put(...)` regardless of mode) and `GetOverviewOperation`
(`totalSlot = assigned + unassigned`): only `unassignedSlot` is always `0`;
`totalSlot` reflects currently assigned slots.
3. `checkpoint-storage.md` (en + zh) used `//` comment lines inside a
```yaml fence — invalid YAML that breaks when copy-pasted; changed to `#`. The
zh HDFS example was also missing the `hdfs_site_path` sample present in en
(supported by `HdfsConfiguration`).
4. `resource-isolation.md` (en + zh) used an invalid fenced-code language
tag `hacon` instead of `hocon`.
5. `user-command.md` (zh) translated two option descriptions inside the
verbatim `bin/seatunnel.sh -h` help block, which no longer matches the actual
CLI output (`ClientCommandArgs.java`).
6. `slot-allocation-strategy.md` (en) lacked the `sidebar_position: 15`
front-matter that zh has, breaking sidebar ordering consistency.
**Transform docs**
7. `table-merge.md` (en + zh): the example uses `table_match_regex`, an
option never documented in the Options table (registered in
`TableMergeTransformFactory.optionRule()` together with `table_transform` /
`rule_match_mode`); the doc also never stated that unmatched tables pass
through unchanged (`AbstractMultiCatalogTransform` identity transform).
8. `encrypt.md` (en + zh): did not document that all `fields` must be
string-typed; `FieldEncryptTransform.initializeFieldIndexes()` throws
`unsupportedDataType` at startup for non-string fields.
9. `metadata.md` (en + zh): claimed `Partition` output is a `string` with
"multiple partition fields separated by commas".
`MetadataTransform.getMetadataFieldValue()` returns the raw row-option value
with no joining logic, and the key is only available when declared by the input
table's `MetadataSchema`.
**Connector docs**
10. Hive sink (en + zh): "example 1" was missing a closing brace, making the
HOCON config invalid; duplicate `### example 2` headings created colliding
anchors (renamed the second to `example 3` / `示例 3`).
11. Hive source + sink (zh): missing the `## 支持的引擎` engine-support section
present in en.
12. HdfsFile source (en + zh): `file_format_type` was marked unconditionally
required, but `HdfsFileSourceFactory.optionRule()` declares it `.optional(...)`
(and per-table `tables_configs` entries carry their own format); aligned with
the LocalFile doc's `conditionally yes` wording.
13. HdfsFile source (en): missing the dedicated `### schema [config]` /
`#### metadata_table_id` sections that zh (and en LocalFile) have.
14. LocalFile source (en): missing the `### metalake_type [string]` section
present in zh (option defined in `TableSchemaOptions`, default `gravitino`).
15. HdfsFile sink + LocalFile sink (zh): the `merge_update_event` table cell
was truncated mid-sentence; completed it to match en and the option's actual
behavior (`FileBaseSinkOptions`).
16. LocalFile sink (zh): excel example missing `schema_save_mode` /
`data_save_mode` lines present in en.
17. Iceberg source (en): missing the `## Source Option descriptions` section
that zh has; Iceberg source examples (en + zh) used a lowercase `iceberg`
plugin identifier (factory identifier is `Iceberg`).
18. Iceberg sink (en + zh): SeaTunnel→Iceberg type mapping table omitted
`TINYINT` / `SMALLINT` (both mapped to `INTEGER` per `IcebergTypeMapper`);
Iceberg source (en + zh) did not document that `LIST` columns are only readable
when the element type is BOOLEAN/INT/BIGINT/FLOAT/DOUBLE/STRING
(`mappingListType` throws otherwise).
19. IoTDBv2 sink (zh): missing the entire "Case 4: Combined TAG, ATTRIBUTE,
and FIELD columns" example present in en; Fluss source (en + zh): `start_mode`
typed as `string` although declared `.enumType(StartMode.class)` in
`FlussSourceOptions`.
## What was changed
All 19 issues above were fixed in place. 31 documentation files updated (156
insertions, 36 deletions), always keeping en and zh in sync.
## Areas / files updated
- `docs/{en,zh}/engines/zeta/`: rest-api-v2, checkpoint-storage,
resource-isolation, user-command, slot-allocation-strategy (10 files)
- `docs/{en,zh}/transforms/`: table-merge, encrypt, metadata, sql (8 files)
- `docs/{en,zh}/connectors/`: Hive (source+sink), HdfsFile (source+sink),
LocalFile (source+sink), Iceberg (source+sink), IoTDBv2 (sink), Fluss (source)
(21 files)
## Were English and Chinese docs both checked?
Yes. Every issue was verified in both language versions, and all fixes were
applied symmetrically to `docs/en` and `docs/zh`.
## How duplicate PRs from the last 7 days were checked
- Listed all PRs authored by @zhangshenghang in the last 7 days (#13097,
#13072, #13050, #12993, #12986, #12971, merged #13121) and excluded every file
they touch; none of the 31 files in this PR appear in those PRs.
- Cross-checked all currently open PRs from any author against the 31
changed files. Four open **feature** PRs touch some of the same files
(13085/13129 Hive compression, 13096 file Word format, 13084 ZSTD ORC): they
add new feature options and do not fix any of the issues in this PR. The only
same-line proximity is the `file_format_type` row in PR 13096 (it adds a new
format to the same cell this PR marks as conditionally required) — the edits
are complementary, but a trivial one-line conflict may need resolving depending
on merge order.
## How the change was verified
- Every option-table claim was checked against the defining Java source
(Options classes, Factory `optionRule()` methods, type mappers), cited per
issue above.
- Automated checks over all 31 changed files: (a) brace balance of every
`hocon`/`yaml` fenced example — all balanced after fixing the Hive sink
example; (b) all relative links resolve to existing files; (c) markdown table
pipe-count consistency — all consistent.
- A full Docusaurus build was not run: this change set contains only content
edits with no front-matter/sidebar structural changes beyond a single
front-matter addition mirroring zh, and the repo's CI has no dedicated docs
build workflow for PRs.
--
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]
