[Docs] Add first-job entry and getting started recipes - #11058
Conversation
DanielLeens
left a comment
There was a problem hiding this comment.
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 intodocs/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:
- The
http-to-jdbcrecipe 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 installconnector-http, but the real plugin artifact and mapping areconnector-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 toconnector-http-base, unless the project first introduces a realconnector-httpalias.
- The expected validation output in
run-your-first-jobdoes not match the actualFieldMapperbehavior.
- 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 pathseatunnel-transforms-v2/.../FieldMapperTransform.java:104-125 - Why this is a blocker:
The sample config explicitly renamesnametonew_name, andFieldMapperTransform.transformTableSchema()builds the output schema from the mapping values. So the documented validation line withname<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
- Blocking items
- Issue 1: fix the
Httpplugin 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.
- 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
left a comment
There was a problem hiding this comment.
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 pathseatunnel-transforms-v2/src/main/java/org/apache/seatunnel/transform/fieldmapper/FieldMapperTransform.java:104-125 - Why this is a blocker:
the sample config renamesnametonew_name, and the runtime schema path really uses the mapped value as the output field name. But the docs still showoutput 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
- 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
FieldMapperresult.
- 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.
|
Validation update for the latest docs-only push (
Scope notes:
|
DanielLeens
left a comment
There was a problem hiding this comment.
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
- The normal first-user path does hit these corrected lines, and both of the previous blockers are now aligned with the real repository behavior.
- The
FieldMapperruntime path still uses the mapping value as the output field name, sonew_name<STRING>is the correct sample output. - The
Httpsource plugin mapping is stillconnector-http-base, and the docs now match that real artifact name. - I did not find a new source-backed blocker on the current head.
Local review note
- I checked
gh pr viewmetadata, the changed-head diff since my previous review, the updated docs content,FieldMapperTransform,config/plugin_config, andplugin-mapping.properties. - I did not run local Maven in this batch; this is a docs-only source-level rereview.
- GitHub
Buildis green on the current head.
Conclusion: can merge
- Blocking items
- None from my side.
- 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.
|
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:
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 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. |
Thanks for your detailed review, I will continue to optimize the doc to make it more user-friendly for new users. |
|
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. |
Purpose of this pull request
This pull request improves the getting started path in the SeaTunnel docs by:
Run your first jobGetting Started -> LocallyGetting Started -> RecipesDoes this PR introduce any user-facing change?
Yes.
Users will now see:
Run your first jobLocallylanding path that includesRun your first jobRecipessection with these scenario guides:Each recipe includes prerequisites, minimal configuration, validation result, and common pitfalls.
How was this patch tested?
Formatting:
./mvnw spotless:applyRepository verification:
./mvnw -q -DskipTests verifyseatunnel-distexport-connector-metadatawith classpath/runtime metadata export noise unrelated to the docs changes../mvnw -q -DskipTests -pl '!seatunnel-dist' verifyWebsite build and UI verification:
seatunnel-websiteworkspace 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 installnpm run buildnpm run serve -- --host 127.0.0.1 --port 3100/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-dorisVerification focus:
Getting Startedsidebar shows the newLocallyentry andRecipescategoryReused artifacts / scope notes:
seatunnel-websiteworkspace as the preview base.Check list
New License Guide
incompatible-changes.mdto describe the incompatibility caused by this PR.