Skip to content

[Docs] Add first-job entry and getting started recipes - #11058

Merged
zhangshenghang merged 5 commits into
apache:devfrom
DanielLeens:daniel-doc-first-job-recipes
Jun 21, 2026
Merged

[Docs] Add first-job entry and getting started recipes#11058
zhangshenghang merged 5 commits into
apache:devfrom
DanielLeens:daniel-doc-first-job-recipes

Conversation

@davidzollo

Copy link
Copy Markdown
Contributor

Purpose of this pull request

This pull request improves the getting started path in the SeaTunnel docs by:

  • adding a new homepage entry card for Run your first job
  • adding a short local first-run guide under Getting Started -> Locally
  • adding 6 practical recipe pages under Getting Started -> Recipes
  • linking the new entry and recipes from the current getting started flow in both English and Chinese docs

Does this PR introduce any user-facing change?

Yes.

Users will now see:

  • a new entry card on the About page that sends first-time users to Run your first job
  • a new Locally landing path that includes Run your first job
  • a new Recipes section with these scenario guides:
    • MySQL CDC -> Doris
    • JDBC -> S3
    • Kafka -> Iceberg
    • Http -> JDBC
    • File -> StarRocks
    • Multi-table CDC

Each recipe includes prerequisites, minimal configuration, validation result, and common pitfalls.

How was this patch tested?

Formatting:

  • ./mvnw spotless:apply

Repository verification:

  • ./mvnw -q -DskipTests verify
    • This failed in the local environment at seatunnel-dist export-connector-metadata with classpath/runtime metadata export noise unrelated to the docs changes.
  • ./mvnw -q -DskipTests -pl '!seatunnel-dist' verify
    • Passed.
    • This was used as the final repository-level verification for this docs-only change.

Website build and UI verification:

  • Copied the local seatunnel-website workspace into a preview directory and synced the current PR docs into that preview using the same directory mapping and image-path rewrite logic used by the website sync flow.
  • npm install
  • npm run build
  • npm run serve -- --host 127.0.0.1 --port 3100
  • Verified these pages in a browser against the local preview:
    • /docs/introduction/about
    • /docs/getting-started/locally/run-your-first-job
    • /docs/getting-started/recipes/mysql-cdc-to-doris
    • /zh-CN/docs/introduction/about
    • /zh-CN/docs/getting-started/recipes/mysql-cdc-to-doris

Verification focus:

  • homepage entry card renders and links correctly
  • Getting Started sidebar shows the new Locally entry and Recipes category
  • recipe pages render with the required sections

Reused artifacts / scope notes:

  • Reused a copied local seatunnel-website workspace as the preview base.
  • No backend runtime artifacts were reused for behavior validation because this PR is documentation-only.
  • No Java unit or integration tests were added because no production code changed.
  • This run did not revalidate connector runtime behavior itself; it revalidated documentation structure, rendering, navigation, and page content.

Check list

@DanielLeens DanielLeens left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting this together. I went through the full docs diff and also checked the corresponding runtime paths and plugin mappings in the repo. The overall direction is good, but I found two blocking accuracy issues that will hit the normal first-time-user path.

What this PR is trying to solve:

  • User pain point: there is no short, official “first job” path plus a small set of runnable getting-started recipes for new SeaTunnel users.
  • Proposed fix: add new onboarding pages under docs/en, docs/zh, and wire them into docs/sidebars.js.
  • In one sentence: the structure is good, but two key facts in the docs are currently out of sync with the actual repo/runtime behavior, so I think we should fix those before merging.

Actual call / usage path I traced:

First-time user follows http-to-jdbc.md
  -> installs plugins from docs/en/getting-started/recipes/http-to-jdbc.md:13
  -> real plugin registration path in repo
      -> config/plugin_config:51 uses connector-http-base
      -> plugin-mapping.properties maps seatunnel.source.Http = connector-http-base
  -> so the documented plugin name is not the real installable artifact

First-time user follows run-your-first-job.md
  -> FakeSource outputs columns name, age
  -> FieldMapperTransform.transformTableSchema() [FieldMapperTransform.java:104-125]
      -> output column name comes from the mapping value
      -> name -> new_name
  -> docs/en/getting-started/locally/run-your-first-job.md:65 still says
     output rowType: name<STRING>, age<INT>
  -> that validation line does not match the actual runtime behavior

Main findings:

  1. The http-to-jdbc recipe uses a plugin name that does not exist in the repo today.
  • Location: docs/en/getting-started/recipes/http-to-jdbc.md:13, docs/zh/getting-started/recipes/http-to-jdbc.md:13
  • Why this is a blocker:
    This is part of the normal installation path for the recipe. The docs say to install connector-http, but the real plugin artifact and mapping are connector-http-base (config/plugin_config:51, plugin-mapping.properties).
  • Risk:
    A new user can fail before even starting the job, purely by following the official docs.
  • Suggested fix:
    Update both EN and ZH docs to connector-http-base, unless the project first introduces a real connector-http alias.
  1. The expected validation output in run-your-first-job does not match the actual FieldMapper behavior.
  • Location: docs/en/getting-started/locally/run-your-first-job.md:65, docs/zh/getting-started/locally/run-your-first-job.md:65, related runtime path seatunnel-transforms-v2/.../FieldMapperTransform.java:104-125
  • Why this is a blocker:
    The sample config explicitly renames name to new_name, and FieldMapperTransform.transformTableSchema() builds the output schema from the mapping values. So the documented validation line with name<STRING> is not what the runtime is expected to produce.
  • Risk:
    Even if the example runs successfully, users may think their installation is broken because the “expected result” in the docs is wrong.
  • Suggested fix:
    Either update the expected output to match the real renamed field, or simplify the example so the schema is not renamed in the first place.

Compatibility:

  • Fully compatible at the code/API level. No API/config/default/protocol/serialization contract is changed.
  • This is a docs-only PR, so the main correctness bar is whether the documented commands and expected results are actually usable. Right now those two points are not.

Performance / side effects:

  • No runtime CPU/memory/GC/network side effects.
  • The practical side effect is onboarding friction: wrong plugin install instructions and a wrong validation target on the main path.

Tests / docs quality:

  • No UT/E2E changes here.
  • Since this is a docs PR, the equivalent of “test coverage” is factual alignment with real repo artifacts and real runtime behavior. That check currently fails on the two points above.

Merge conclusion:

Conclusion: can merge after fixes

  1. Blocking items
  • Issue 1: fix the Http plugin install name in both EN and ZH docs so it matches the real repo artifact.
  • Issue 2: fix the expected output in run-your-first-job, or simplify the example so the documented validation result becomes true.
  1. Non-blocking suggestions
  • No extra non-blocking items from my side. Once the two accuracy issues above are fixed, the rest of the structure looks good.

Overall, I like the onboarding direction here. The only reason I’m holding this is that first-job / getting-started pages need to be exact on the normal path. Happy to re-review once you update those two points.

@DanielLeens DanielLeens left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. I re-reviewed the latest docs against the real plugin mapping and the actual FieldMapper runtime path. One of my previous documentation blockers is fixed on the current head, but two user-facing facts are still not aligned with the repository behavior yet.

What This PR Solves

  • User pain: SeaTunnel needs a clearer first-job path and practical source-to-sink recipes for new users.
  • Fix approach: add getting-started pages, recipes, and sidebar entries.
  • One-line summary: the onboarding direction is good, but the current docs still have one incorrect plugin-install step and one still-stale expected output sample on the normal first-run path.

User Path Rechecked

New user follows the HTTP -> JDBC recipe
  -> docs/.../http-to-jdbc.md:13
      -> installs connector-http
  -> real plugin mapping in the repo
      -> config/plugin_config: connector-http-base
      -> plugin-mapping.properties: seatunnel.source.Http = connector-http-base

New user runs the FakeSource -> FieldMapper -> Console quick start
  -> FieldMapperTransform.transformTableSchema() [FieldMapperTransform.java:104-125]
      -> output column name uses the mapped value
      -> name -> new_name
  -> docs/.../quick-start-seatunnel-engine.md:112
      -> sample output still says name<STRING>, age<INT>

Findings

Issue 1: the HTTP -> JDBC recipe still tells users to install connector-http, but the real installable plugin is still connector-http-base

  • Location: docs/en/getting-started/recipes/http-to-jdbc.md:13, docs/zh/getting-started/recipes/http-to-jdbc.md:13
  • Why this is a blocker:
    this is the first actionable step in the recipe, and it still does not match the actual plugin registration in the repo.
  • Better fix:
    update both docs to the real plugin artifact name, or add a real alias first before documenting it.
  • Severity: High
  • Already raised by others: No

Issue 2: the quick-start console sample still does not match the real FieldMapper output schema

  • Location: docs/en/getting-started/locally/quick-start-seatunnel-engine.md:112, docs/zh/getting-started/locally/quick-start-seatunnel-engine.md:111, related runtime path seatunnel-transforms-v2/src/main/java/org/apache/seatunnel/transform/fieldmapper/FieldMapperTransform.java:104-125
  • Why this is a blocker:
    the sample config renames name to new_name, and the runtime schema path really uses the mapped value as the output field name. But the docs still show output rowType: name<STRING>, age<INT>.
  • Better fix:
    either update the log sample to the real output, or simplify the example so it no longer renames the field.
  • Severity: High
  • Already raised by others: No

Merge Conclusion

Conclusion: can merge after fixes

  1. Blocking items
  • Issue 1: fix the HTTP plugin-install name in the recipe.
  • Issue 2: fix the quick-start output sample so it matches the real FieldMapper result.
  1. Suggested follow-up
  • No extra non-blocking items from me on this revision.

Overall, this is very close. The main thing left is to make sure the “first user run” instructions are factually correct end to end.

@davidzollo
davidzollo marked this pull request as draft June 11, 2026 13:59
@DanielLeens

Copy link
Copy Markdown
Contributor

Validation update for the latest docs-only push (556701adae):

  • ./mvnw spotless:apply
    • Passed.
  • ./mvnw -q -DskipTests verify
    • Failed locally at seatunnel-dist export-connector-metadata.
    • Observed error: exec-maven-plugin reported org/apache/seatunnel/api/table/factory/TableSinkFactory missing during connector metadata export.
  • Website preview validation reused the existing local preview workspace and its existing node_modules:
    • Preview workspace: /Users/stone/work/myworkspace/seatunnel-website.worktrees/f867-doc-preview3.sZWOZW
    • npm run build
      • Passed and generated both build/ and build/zh-CN/.
    • npm run serve -- --host 127.0.0.1 --port 3100
  • Verified all touched tutorial pages in browser preview for both English and Chinese:
    • run-your-first-job
    • mysql-cdc-to-doris
    • jdbc-to-s3
    • kafka-to-iceberg
    • http-to-jdbc
    • file-to-starrocks
    • multi-table-cdc
  • Verified the new installation links jump to the correct sections:
    • /docs/getting-started/locally/deployment#download-the-connector-plugins
    • /zh-CN/docs/getting-started/locally/deployment#下载连接器插件

Scope notes:

  • Reused only the preview website workspace and its existing node_modules.
  • This run did not revalidate the real connector runtime behavior of MySQL, Kafka, Doris, S3, Iceberg, PostgreSQL, StarRocks, or HTTP systems, because this PR is documentation-only and no shared full integration environment for all six recipes was provisioned in this run.
  • This run did revalidate documentation structure, static build output, page rendering, navigation, and anchor-link behavior for every touched tutorial page.

@davidzollo
davidzollo marked this pull request as ready for review June 12, 2026 07:13
@apache apache deleted a comment from DanielLeens Jun 15, 2026

@DanielLeens DanielLeens left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. I re-reviewed the latest docs-only head specifically against the two blockers from my previous review, using the real plugin mapping and the actual FieldMapper schema path in the repo.

What this PR solves

  • User pain: SeaTunnel needs a clearer first-job path and a practical set of getting-started recipes for new users.
  • Fix approach: add onboarding pages under docs/en, docs/zh, and wire them into the sidebar.
  • One-line summary: this is a docs-focused onboarding improvement, and the two factual blockers from my previous round are now fixed on the current head.

Runtime / usage path I rechecked

New user follows the HTTP -> JDBC recipe
  -> docs/.../http-to-jdbc.md
      -> plugin name is now connector-http-base
  -> real repo mapping
      -> config/plugin_config: connector-http-base
      -> plugin-mapping.properties: seatunnel.source.Http = connector-http-base

New user runs the FakeSource -> FieldMapper -> Console quick start
  -> FieldMapperTransform.transformTableSchema() [104-125]
      -> output column name uses the mapping value
      -> name -> new_name
  -> docs/.../quick-start-seatunnel-engine.md
      -> sample output now says new_name<STRING>, age<INT>

Key findings

  1. The normal first-user path does hit these corrected lines, and both of the previous blockers are now aligned with the real repository behavior.
  2. The FieldMapper runtime path still uses the mapping value as the output field name, so new_name<STRING> is the correct sample output.
  3. The Http source plugin mapping is still connector-http-base, and the docs now match that real artifact name.
  4. I did not find a new source-backed blocker on the current head.

Local review note

  • I checked gh pr view metadata, the changed-head diff since my previous review, the updated docs content, FieldMapperTransform, config/plugin_config, and plugin-mapping.properties.
  • I did not run local Maven in this batch; this is a docs-only source-level rereview.
  • GitHub Build is green on the current head.

Conclusion: can merge

  1. Blocking items
  • None from my side.
  1. Suggested follow-up
  • No additional follow-up items from this rereview.

Overall, this is ready from my side. The latest head fixes the two documentation accuracy issues that were blocking the previous revision.

@weifuwan

Copy link
Copy Markdown

I reviewed this PR mainly from the first-time user onboarding perspective. Overall, I think the direction is good. Adding a clear "Run your first job" entry and several practical getting-started recipes can make the SeaTunnel documentation much friendlier for new users.

I especially like that the recipes cover common real-world scenarios, such as MySQL CDC to Doris, JDBC to S3, Kafka to Iceberg, HTTP to JDBC, File to StarRocks, and multi-table CDC.

I also checked the previous review concerns around the HTTP connector plugin name and the FieldMapper expected output. The latest revision appears to have aligned these points with the actual repository behavior:

  • HTTP source uses connector-http-base
  • FieldMapper output uses the mapped field name new_name

From my side, I do not see a blocking issue in this docs-only PR. The structure is clear, the onboarding path is useful, and the current changes look good to me.

LGTM.

@DanielLeens

Copy link
Copy Markdown
Contributor

Thanks for the careful follow-up from the onboarding angle. I agree the latest revision resolved the two documentation-accuracy points I had raised earlier around the HTTP connector naming and the FieldMapper output description. Since there is no new docs diff after the approval, I am not starting another full review round here; from my side this stays in the approved / waiting-for-CI-and-maintainer state.

@davidzollo

Copy link
Copy Markdown
Contributor Author

I reviewed this PR mainly from the first-time user onboarding perspective. Overall, I think the direction is good. Adding a clear "Run your first job" entry and several practical getting-started recipes can make the SeaTunnel documentation much friendlier for new users.

I especially like that the recipes cover common real-world scenarios, such as MySQL CDC to Doris, JDBC to S3, Kafka to Iceberg, HTTP to JDBC, File to StarRocks, and multi-table CDC.

I also checked the previous review concerns around the HTTP connector plugin name and the FieldMapper expected output. The latest revision appears to have aligned these points with the actual repository behavior:

  • HTTP source uses connector-http-base
  • FieldMapper output uses the mapped field name new_name

From my side, I do not see a blocking issue in this docs-only PR. The structure is clear, the onboarding path is useful, and the current changes look good to me.

LGTM.

Thanks for your detailed review, I will continue to optimize the doc to make it more user-friendly for new users.

@DanielLeens

DanielLeens commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

Thanks. I rechecked the thread here and there is still no new docs diff after my last approval. From my side this remains in the approved / waiting-for-maintainer state.

@zhangshenghang
zhangshenghang merged commit b5fd760 into apache:dev Jun 21, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants