lucasfang opened a new issue, #491: URL: https://github.com/apache/paimon-cpp/issues/491
## Search before asking - [x] I searched in the [issues](https://github.com/apache/paimon-cpp/issues) and found nothing similar. ## Motivation The published documentation at https://paimon.apache.org/docs/cpp/ is a single build of the main branch. A reader who uses the released 0.3 library therefore reads pages that describe unreleased behavior, with nothing on the page telling them so and no way to reach the documentation matching their binary. `docs/source/_static/versions.json` exists but holds a single `0.4.0` entry pointing at the site root, so even if a dropdown were rendered it would offer one wrong choice. The current `versions.json` also claims the unreleased 0.4.0 is what lives at `docs/cpp/`, which will stop being true the moment a release is cut: nothing maintains the list, so it is already drifting. Documentation changes themselves are not build-validated on pull requests either, so a broken docs build is only discovered after landing on main. ## Solution Ship the layout the pydata-sphinx-theme version switcher expects, as Apache Arrow does: - A version dropdown in the navbar, driven by `docs/source/_static/versions.json` with a dev/stable/archived layout: `main (development)` at `docs/cpp/main/`, the latest stable release (preferred) at `docs/cpp/`, and archived `X.Y` series at `docs/cpp/X.Y/`. - A documentation channel selected at build time by `PAIMON_DOCS_VERSION`: unset or `main` builds main-branch docs carrying a `.dev` release suffix, which makes the theme show an "unstable development version" banner with a switch-to-stable link; `stable` builds the latest release with no banner; `X.Y` builds an archived series. - `scripts/releasing/bump_version.py` becomes the maintainer of the version list: a new major.minor series rotates the stable entry and archives the previous series, a patch cycle leaves the list untouched, and `--check` validates the whole layout so release metadata cannot drift silently. - The docs workflow gains a `pull_request` trigger so `apidoc/`, `docs/` and `include/` changes are build-validated before merge; the existing gh-pages deployment on push to main is unchanged. - Publishing `docs/cpp/`, `docs/cpp/main/` and `docs/cpp/<X.Y>/` on the website is a follow-up change on apache/paimon-website, which can discover the version list from this repository so it needs no update per release. ## Anything else? Local preview note for reviewers: the switcher JSON URL defaults to the live site and can be overridden with `PAIMON_DOCS_VERSIONS_URL`, which must be an absolute URL reachable from the browser (for example `http://<host>:<port>/_static/versions.json`), not a relative path or a `file://` URL. ## Are you willing to submit a PR? - [x] I'm willing to submit a PR! -- 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]
