apache / apache/incubator-xtable

Docs: address the open review comments on the 0.4.0 Spark runtime quickstart and Downloads page

Open
#920 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.