[lucasfang]

Purpose

Linked issue: close #491

Add a documentation version dropdown and a development-version warning banner so readers can distinguish released documentation from main-branch documentation.

• List main at docs/cpp/main/ and 0.3.0 (stable) at docs/cpp/. The development entry is labeled simply main; metadata validation also accepts the previous label when auditing older Git refs. Stable and archived labels show full release versions; archived identifiers and URLs retain their major.minor series.
• Select the channel with PAIMON_DOCS_VERSION: unset or main adds a .dev release suffix; stable explicitly disables the warning banner; X.Y selects an archived series. Set the documentation version to 0.3.0. Override the switcher JSON URL with PAIMON_DOCS_VERSIONS_URL for previews.
• Use the same metadata validator for source archive creation and verification, reading metadata from the requested immutable Git ref. This supports the stable documentation version while still rejecting unrelated versions and ignoring working-tree edits.
• Validate the version list in bump_version.py --check. Release preparation updates the stable label to the target full version and archives the previous stable release only when its series changes. Patch releases update the label without adding an archive. The checker allows documentation to track the stable release while CMake advances, and version updates bring both to the target version.
• Build documentation on pull requests affecting apidoc/, docs/, or include/, and include the docs workflow in release-candidate validation triggers. Deployment runs only on pushes to main.
• Fix short heading underlines and remove the redundant FullTextScan::Plan directive: the enclosing class already renders the nested class and its members.

Publishing the versioned directories requires a companion change in apache/paimon-website and the documentation channel configuration on release branches.

Tests

• python3 -m unittest discover -s scripts/releasing/tests -p 'test_*.py' — 20 tests passed, including full version labels, patch label updates without duplicate archives, upgrades from a previous stable documentation version, channel-specific banner configuration, and immutable-ref archive validation when documentation tracks a prior stable release.

• pre-commit run --files docs/source/_static/versions.json docs/source/api/global_index.rst docs/source/conf.py docs/source/user_guide/file_index.rst scripts/releasing/README.md scripts/releasing/bump_version.py scripts/releasing/tests/test_release_tools.py — all applicable checks passed.

• git diff --check — passed.

• python3 scripts/releasing/bump_version.py --check 0.4.0 and python3 scripts/releasing/bump_version.py --dry-run 0.4.0 0.5.0 — passed.

• Regenerated API XML with doxygen Doxyfile in apidoc/. Doxygen completed with warnings about unsupported configuration tags in the installed version.

• Full Sphinx builds passed for both PAIMON_DOCS_VERSION=stable and main, using Python 3.11.15 and make html SPHINXOPTS='-j8 -E -a -W --keep-going' with separate output directories and a local PAIMON_DOCS_VERSIONS_URL. Both Sphinx builds completed with zero warnings.

• Local HTTP checks verified both channels, the version JSON, destination pages, and unique anchors for the nested Plan API. The local dropdown was confirmed working in the browser after using a browser-reachable preview address.

• Created a real source archive from the CI fix commit and ran GZIP=-9 scripts/releasing/verify_release_candidate.sh --allow-unsigned --git-ref HEAD --skip-build --rat-jar <local-apache-rat-0.16.1.jar> <archive> — checksum, archive layout, metadata, Git-ref reproducibility, and Apache RAT all passed. C++ compilation was skipped.

• bash -n scripts/releasing/create_source_release.sh and pre-commit checks for the archive creator and regression tests — passed.

API and Format

No C++ public API, storage format, or protocol changes. The environment variables configure documentation builds only. Version-list display names now use full release versions; archived paths remain major.minor.

Documentation

Adds the version switcher, channel-specific warning configuration, version-list maintenance and release-preparation guidance. Updates the documentation version to 0.3.0 and fixes Sphinx heading and duplicate-declaration warnings.

Local preview overrides and generated files are excluded from the commit. The production switcher retains its paimon.apache.org URL and requires the website publishing changes.

Generative AI tooling

Generated-by: Qoder
Generated-by: OpenAI Codex (GPT-6)

[lszskye]

+1

[lxy-9602]

+1