zhangshenghang opened a new pull request, #13062:
URL: https://github.com/apache/seatunnel/pull/13062
Yes, I am happy to contribute to Apache SeaTunnel.
## What documentation issues were found
This batch fixes real documentation inaccuracies found by auditing connector
docs against the actual source code on `dev`. Every fix below cites the code
that proves the doc wrong.
1. **MongoDB sink (EN+ZH)** — Docs claimed the configured `primary-key` is
written as the MongoDB `_id` (compound `_id`). In fact
`RowDataDocumentSerializer` uses the primary-key fields as the upsert **match
filter** and explicitly removes `_id` (`bsonDocument.remove("_id")`), so
MongoDB auto-generates it. The type table also claimed SeaTunnel `Timestamp`
maps to `Timestamp[Date]` / `Timestamp / Date`, and a tip claimed `Date` is
second-precision — both contradict `RowDataToBsonConverters`, where `DATE` and
`TIMESTAMP` are both written as millisecond `BsonDateTime` (a `Date` becomes
midnight of that day). Fixed the description, the mapping row, the tip, and the
"Idempotent Writes" section.
2. **Opengauss-CDC (EN+ZH)** — The "CDC Metadata Fields" table listed keys
`database`, `table`, `rowKind`, `ts_ms`, `delay`, but `CommonOptions` registers
`Database`, `Table`, `RowKind`, `EventTime`, `Delay`, and `MetadataTransform`
rejects unknown/case-mismatched keys. The doc's own example already used the
correct keys, contradicting its table. Fixed the table, corrected the
`EventTime` description (connector fetch/processing time, not the source event
time), and added a note that keys are case-sensitive.
3. **Paimon (ZH)** — The ZH `table_list` section said each item only needs
`table`, and the ZH multi-table example omitted the per-item `database`. Each
`table_list` entry is parsed in isolation (`PaimonSourceTableConfig.of` →
`ReadonlyConfig.fromMap` per item), so a missing per-item `database` fails the
table lookup. Aligned the ZH prose and example with the (already correct) EN
doc. Also, the ZH sink schema-evolution list translated "Renaming columns" as
the vague "更改列"; replaced it with an accurate rename bullet matching EN and
`AlterPaimonTableSchemaEventHandler`.
4. **LocalFile (EN+ZH)** — The ZH sink doc had a broken `xml_root_tag`
heading split into `### xml` + `_root_tag [string]`, and its `field_delimiter`
description omitted `csv` although CSV writes consume the option
(`BaseFileSinkConfig`/`CsvWriteStrategy`; EN says "text and csv"). The source
doc marked `file_format_type` as unconditionally required, but
`LocalFileSourceFactory.optionRule()` marks it optional — it is required only
for single-table `path` mode, while each `tables_configs` entry defines its
own. Changed to "conditionally yes" / "视情况而定" (the same convention already used
by the `schema` row) and added a clarifying note.
5. **OneSignal (EN+ZH)** — The `headers` row said a user-supplied
`Authorization` header overrides the generated one; the code does the opposite:
`OneSignalSourceParameter` puts `Authorization: Basic <password>` into the
headers map *after* loading user headers, overwriting any user value (the doc's
own Usage Notes already stated this correctly). Fixed the contradictory table
row. Also removed the nonexistent `page_step` key from the pagination example —
`HttpSource.buildPagingWithConfig` supports no such option.
6. **Jira (EN+ZH)** — Same reversed `Authorization` claim;
`JiraSourceParameter` overwrites any user `Authorization` with the Basic header
generated from `email`/`api_token`.
7. **GoogleSheets (EN+ZH)** — Examples used `service_account_key =
"seatunnel-test"`, which is not valid Base64; `SheetsSourceReader.open()`
decodes it with `Base64.getDecoder()` and throws `IllegalArgumentException`
before any connection. Replaced with an explicit `<base64-encoded service
account JSON>` placeholder consistent with the option's documented format.
8. **Hive source (EN)** — The description said "Each table can be read as
one batch split", but `MultipleTableHiveSourceSplitEnumerator` creates one
split per data file (it iterates the per-table file lists from
`readStrategy.getFileNamesByPath`), which is what actually provides the
documented parallelism. Reworded accordingly.
9. **SqlServer-CDC (EN+ZH)** — The Debezium properties link pointed to the
Debezium **1.6** docs, but the connector embeds Debezium 1.9.8.Final
(`connector-cdc/pom.xml`). Updated to the 1.9 reference page, matching the link
style already used by the DB2-CDC doc.
10. **Source common options (EN+ZH)** — The table claims to list the common
source parameters but omitted `dag-parsing.mode`
(`SourceConnectorCommonOptions.DAG_PARSING_MODE`, enum
`SINGLENESS`/`MULTIPLEXING`, default `SINGLENESS`), which was documented
nowhere under `docs/en` or `docs/zh`. Added the row with the code's semantics.
## What was changed
20 documentation files (9 English + 11 Chinese), 56 insertions / 46
deletions. All changes are real content fixes (option semantics, metadata keys,
examples, links, required flags); no formatting-only churn.
Areas updated: MongoDB sink, Opengauss-CDC, SqlServer-CDC, Paimon,
LocalFile, OneSignal, Jira, GoogleSheets, Hive, source common options — each in
`docs/en` and, where the same wrong text existed, `docs/zh`.
## English and Chinese docs both checked
Yes. Every issue was fixed in the English doc and, when the same wrong text
existed, in the Chinese doc as well (11 of the 20 files are `docs/zh` mirrors).
The ZH-only divergences (Paimon `table_list` example, LocalFile broken heading
/ `field_delimiter`, Paimon rename bullet) were found by cross-checking ZH
against EN and code.
## Duplicate PR check (last 7 days)
Before opening this PR I reviewed the docs PRs from the past week via the
GitHub API: #13050, #12993, #12986, #12971, #12865 (open) and #13019, #11705
(merged). None of the 20 files touched here appears in their changed-file
lists, and none of the issues above overlaps their scope, so this PR does not
duplicate them.
## How the change was verified
- Each fixed statement was verified against the source:
`RowDataDocumentSerializer`, `RowDataToBsonConverters`, `CommonOptions`,
`MetadataTransform`, `PaimonSourceTableConfig`, `LocalFileSourceFactory`,
`BaseFileSinkConfig`/`CsvWriteStrategy`, `OneSignalSourceParameter`,
`JiraSourceParameter`, `SheetsSourceReader`,
`MultipleTableHiveSourceSplitEnumerator`, `SourceConnectorCommonOptions`.
- Ran a repo-wide relative-link check over all `docs/en` + `docs/zh`
markdown files: no broken links introduced (the only reported entries are 4
pre-existing false positives from inline code in
`transforms/dynamic-compile.md`, untouched by this PR).
- Verified markdown table integrity (column/pipe counts) in all changed
files.
- Confirmed the replacement Debezium 1.9 link returns HTTP 200.
- This PR is docs-only; no Java code, configuration, or build files changed,
so Maven builds/tests are not affected and were not run.
--
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]
