zhangshenghang opened a new pull request, #13204:
URL: https://github.com/apache/seatunnel/pull/13204

   Yes — this is a contribution to **Apache SeaTunnel**.
   
   ### Purpose of this pull request
   
   This PR fixes documentation that contradicts the current source code on 
`dev`: Java API snippets on the architecture pages, connector examples that 
cannot run, wrong option statements, and stale CLI/version details. English and 
Chinese pages were checked together and fixed together wherever both had the 
problem. Every change was checked against the code referenced below.
   
   There is no tracking issue. This is a documentation-only correctness fix.
   
   ### What documentation issues were found and what was changed
   
   **1. Architecture API pages show APIs that do not exist 
(`architecture/api-design`)**
   
   - `sink-architecture.md` (en, zh)
     - `SinkCommitter` and `SinkAggregatedCommitter` were shown as `extends 
Closeable`. In the code they `extend Serializable`.
     - Both `abort(...)` methods were shown as optional `default` no-ops. In 
the code they are abstract (`SinkAggregatedCommitter#abort` throws 
`Exception`), so implementers must write them.
     - `SinkCommitter#close()` was shown but does not exist.
     - `restoreCommit(...)` was shown as a `void` no-op. Its real default calls 
`commit(...)` again.
     - `init()` was missing.
     - `SinkWriter#prepareCommit(long)` and `snapshotState(long)` were shown as 
abstract. In the code they are defaults, and the deprecated no-arg 
`prepareCommit()` is the abstract method.
     - The page said the committer "runs on master". This contradicts section 
2.2 of the same page and `SinkFlowLifeCycle#notifyCheckpointComplete`, which 
runs it in the worker-side sink task.
     - The page said `abortPrepare()` is "only used by Spark". 
`SinkFlowLifeCycle#abortPreparedWriter` also calls it on the SeaTunnel Engine.
     - The zh page called `abort` "(optional)".
     - The example committers now implement the abstract methods.
   - `source-architecture.md` (en)
     - The `SeaTunnelSource` parent interfaces were incomplete: 
`PluginIdentifierInterface` (which requires `getPluginName()`), 
`SeaTunnelPluginLifeCycle` and `SeaTunnelJobAware` were missing.
     - `getSplitSerializer()` and `getEnumeratorStateSerializer()` were shown 
as abstract. They are defaults that return `DefaultSerializer`.
   - `catalog-table.md` (en, zh)
     - The page taught a `DataTypes.TINYINT()/VARCHAR(n)/ROW(...)` factory that 
does not exist anywhere in SeaTunnel. All snippets now use the real types: 
`BasicType`, `DecimalType`, `LocalTimeType`, `PrimitiveByteArrayType`, 
`ArrayType.of`, `MapType`, `SeaTunnelRowType`.
     - `Column.builder()` does not exist (`Column` is abstract). Replaced with 
`PhysicalColumn.builder()`.
     - `TableSchema.Builder#column(String, type)`, `primaryKey(String)` and 
`constraint(...)` do not exist. Replaced with `column(Column)`, 
`primaryKey(PrimaryKey)` and `constraintKey(...)`.
     - `SchemaChangeEvent` is an interface extending `Event`, not an abstract 
class with a `tableId` field. `AlterTableAddColumnEvent` has no two-argument 
constructor; the snippets now use the `add(...)` factories.
     - The schema-override example used a `JDBC` block with `schema { fields 
}`. `Jdbc` derives its schema from metadata, and its `schema` option is the 
database schema name. The example now uses Kafka.
     - The `schema-evolution { enabled, auto-add-column, ... }` block does not 
exist. It is replaced with the real `schema-changes.enabled` (CDC source) plus 
`schema_save_mode`, matching what the zh page already said.
   - `translation-layer.md` (en, zh)
     - Flink adapters:
       - `FlinkSource` and `FlinkSourceReader` produce `SeaTunnelRow` and have 
no `<T>` type parameter.
       - `EnumeratorStateWrapper`, `CollectorAdapter` and 
`SplitWrapper#getSplit` do not exist. The real names are `EnumStateT`, 
`FlinkRowCollector` and `getSourceSplit()`.
       - The split serializer is `SplitWrapperSerializer`.
       - The enumerator `start()` only calls `open()`. `run()` is called from 
`addReader()` (via `registerReader`, not `addReader`) after all readers 
register.
       - `sendSplitRequest()` forwards to Flink; it is not a no-op.
       - `FlinkSink`/`FlinkSinkWriter` use `CommitWrapper`/`FlinkWriterState`, 
with `CommitWrapperSerializer`/`FlinkWriterStateSerializer`.
     - Spark adapters:
       - `SparkSource`, `SparkInputPartition`, `SparkPartitionReader`, 
`SparkCommitMessage` and `SparkTypeConverter` do not exist. The real classes 
are now used: `BatchSourceReader`, `BatchPartition`, 
`SeaTunnelInputPartitionReader`, `SparkDataSourceWriter`, 
`SparkWriterCommitMessage` and `TypeConverterUtils`.
       - Splits are not enumerated on the driver. There is one virtual 
partition per subtask, running `ParallelSource`/`CoordinatedSource`.
       - The driver-side commit goes through `SinkAggregatedCommitter`.
     - `FlinkSimpleVersionedSerializer#getVersion()` returns `0`; SeaTunnel's 
`Serializer` has no `getVersion()`.
     - The zh prose had the same wrong statements and is fixed too.
   
   **2. Connector docs**
   
   - `sink/SensorsData.md` (en, zh)
     - The *Item Tracking* example did not set `entity_name = items`. With the 
default `users`, `record_type = items` throws `UNSUPPORTED_RECORD_TYPE` in 
`SensorsDataRecordBuilder`. The example now uses only the options item records 
use.
     - The *Console Output* example missed `identity_fields`. With the default 
`entity_name = users` it is conditionally required 
(`SensorsDataBaseOptionRules`), so validation fails.
   - `source/GoogleBigtable.md` (en, zh): the options table had no `schema` 
row. The source calls `CatalogTableUtil.buildWithConfig`, which fails with 
`Schema config need option [schema]` when it is missing. Added the row and a 
`schema [config]` section.
   - `source/Phoenix.md` (en, zh): the docs said the SELECT order "must match 
`schema.fields`". The JDBC source has no such option; the schema is derived 
from the query.
   - `source/Vertica.md` (en, zh): the docs said `partition_column` was 
"numeric only". `ChunkSplitter#isSupportSplitColumn` and `FixedChunkSplitter` 
also support STRING and DATE.
   
   **3. Developer, deployment and getting-started docs**
   
   - `developer/setup.md` (en, zh): the docs required Scala 2.11.12. The build 
uses `scala.version` 2.12.15.
   - `developer/coding-guide.md` (en, zh): the example threw a nonexistent 
`SeaTunnelORCFormatException` without `new`. It now uses 
`FileConnectorException` with `FileConnectorErrorCode.FILE_READ_FAILED`.
   - `getting-started/application/kubernetes/configuration.md`, `faq.md` (en, 
zh): the docs warned against passing `kubernetes.kubeconfig` with `-i`. 
`ApplicationCommandArgs` has no `-i`; overrides use `-D`, as the same page's 
caution box already says.
   - `getting-started/kubernetes/configuration.md` (en, zh): the IMap 
`storage.type` list missed `gcs` (`FileConfiguration` has HDFS/S3/OSS/GCS).
   - `getting-started/locally/quick-start-flink.md`, `quick-start-spark.md` 
(en, zh): the sample output (`fields : name, age` / `row=1 : ...`) is not 
printed by any current code.
     - It is replaced with the `ConsoleSinkWriter` format (`output rowType: 
...`, `subtaskIndex=... rowIndex=...`).
     - `FieldMapper` emits fields in `field_mapper` order (`age`, then 
`new_name`). I confirmed the key order is preserved with a small run against 
`ReadonlyConfig`, which returns `LinkedHashMap {age=age, name=new_name}`.
   
   ### Which areas/files were updated
   
   29 files, documentation only: `docs/en` + `docs/zh` under 
`architecture/api-design`, `connectors/source`, `connectors/sink`, `developer`, 
`getting-started/application/kubernetes`, `getting-started/kubernetes`, 
`getting-started/locally`. No code, config option, default value or API changed.
   
   ### Whether English and Chinese docs were both checked
   
   Yes. Every page was checked in both languages, and both were fixed where 
both had the problem. `source-architecture.md` is changed in en only, because 
the zh page has no code snippet and its statements are accurate.
   
   ### How duplicate PRs from the last 7 days were checked
   
   - Listed every PR created since 2026-11-03 (63 PRs) with `gh pr list 
--search "created:>=2026-11-03"` and compared their changed files with this PR. 
No overlap remains.
   - One fix (zh `local-mode-deployment.md` `-e local` → `-m local`) was 
dropped because #13149 already contains it.
   - Also compared against all 368 open PRs, including older ones. The 
Cloudberry `timer flush` and MySQL `partition_column` fixes were dropped 
because #11782 already proposes them.
   - Other open PRs touch different lines of the same files: #11704, #11713, 
#12943, #13015, #12328, #11174, #10874. None makes the same fix.
   - The zh Windows `cd apache-seatunnel-3.0.0` mismatch is already fixed in 
#13193, so it is not repeated here.
   
   ### Does this PR introduce any user-facing change?
   
   Yes, documentation only. The docs now match the current behaviour; nothing 
in the product changes.
   
   ### How was this patch tested?
   
   - Relative link and anchor check over all `docs/en` and `docs/zh` pages: no 
new broken links. This includes the new `#schema-mapping` / `#schema-映射` 
anchors.
   - `markdown-link-check -c .dlc.json` (the CI dead-link tool) on all 29 
changed files: no dead links.
   - A scan of the newly added text for MDX-unsafe `<tag` / `{...}` outside 
code: none introduced.
   - `./mvnw spotless:check`: passed. Markdown formatting is disabled in the 
Spotless config, so it does not cover these files.
   - Every changed statement and snippet was checked against the cited classes 
on current `dev`. The `FieldMapper` key order was confirmed with a small Java 
program run against the built `seatunnel-api` classes.
   - Not run: the full Docusaurus website build. It needs the separate 
`seatunnel-website` repository, and the PR CI `Build website` job covers it.
   
   ### Check list
   
   - [x] Documentation in both `docs/en` and `docs/zh` updated where applicable.
   - [x] No incompatible changes.
   


-- 
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]

Reply via email to