apache / apache/incubator-xtable
Docs: address the open review comments on the 0.4.0 Spark runtime quickstart and Downloads page
- Dominant language
- Java
- Stars
- 1.2k
- Forks
- 212
- Avg merge
- 4d 9h
- Merged PRs (30d)
- 16
Description
Follow-up to #913, which was merged before the review comments on it were addressed.
The Spark runtime quickstart (`website/docs/how-to-spark-runtime.md`), the Downloads page
(`website/releases/downloads.mdx`) and the 0.4.0 release notes
(`website/releases/release-0.4.0-incubating.mdx`) landed with a set of open review comments.
This issue tracks addressing them.
### `website/docs/how-to-spark-runtime.md`
1. **Section order.** "Adding the sync to a Spark job" comes before "Running a sync as its own
job". A new reader meets `orders-job.jar` in a `spark-submit` before anything explains what
that jar is. The standalone entry point is the simpler starting point and should come first.
2. **Build before submit.** Within the in-job section, the `spark-submit` command appears before
the code it submits. Cover writing and building the job first, then how to run it.
3. **Path style.** The examples use `s3://example-warehouse/db/orders`, while the existing
Quickstart (`/docs/how-to`) walks through local `/tmp/...` paths. Use local paths here too so a
reader can follow both pages with the same setup.
4. **Prerequisite.** The `spark-submit` example syncs a Hudi table that the page never creates.
Say up front that the source table has to exist, and link the Quickstart for creating one.
5. **Single table vs multiple tables.** `XTableSparkSync` can run from CLI flags or from
`--datasetconfig`. The page shows both but does not frame them as the two modes they are.
Give each its own subsection.
6. **Visibility of the Delta note.** The paragraph explaining which Delta implementation is used
on which Spark line is easy to miss as plain body text. Promote it to a `:::note`.
7. **"and newer".** The Spark version table says `3.5.x and newer`, which reads as a promise of
Spark 4.x support. The 0.4.0 build is pinned to Spark 3.4.2 with
`spark.version.prefix=3.4`, and `hudi-spark3.4-bundle` / `iceberg-spark-runtime-3.4`; the
bundle smoke test covers the 3.4 and 3.5 lines only. State the supported versions explicitly.
8. **Broken link (already resolved).** The `demo/spark-runtime` link returned 404 at review time
because the directory did not yet exist on `main`. Merging #913 created it and the link now
resolves. Recorded here for completeness; no change needed.
### `website/releases/downloads.mdx`
9. **Release headings are not links.** Each `### Release x.y.z-incubating` heading is plain text.
Link each one to its release notes page so the heading itself is navigable.
10. **Sidebar order.** Downloads renders last in the Releases sidebar, below every release-notes
entry, because the release pages use negative `sidebar_position` values (`-4`, `-3`, `-2`)
while `downloads.mdx` uses `1`. Downloads is the entry point for that section and should be
first.
### `website/releases/release-0.4.0-incubating.mdx`
11. **Spark support callout.** Spark 3.4 and 3.5 support for `xtable-spark-runtime` is mentioned
mid-paragraph. Promote it to a callout so it is visible when skimming the release notes.
### Verification
All facts above were checked against the `0.4.0-incubating` tag (root `pom.xml`,
`xtable-spark-runtime/pom.xml`, `XTableSparkSync.java`, `ITXTableSparkRuntimeBundle.java`) rather
than `main`, since `xtable-spark-runtime` exists only on the 0.4.x release line.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the three named files: website/docs/how-to-spark-runtime.md, website/releases/downloads.mdx, and website/releases/release-0.4.0-incubating.mdx. Use the 0.4.0-incubating tag and the referenced pom.xml, XTableSparkSync.java, and ITXTableSparkRuntimeBundle.java to verify supported Spark versions and terminology. Done means addressing review items 1–7 and 9–11, while leaving the already-resolved link unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spark
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100