andygrove opened a new pull request, #7112: URL: https://github.com/apache/datafusion-comet/pull/7112
## Which issue does this PR close? N/A. This is a docs publishing change with no existing issue. ## Rationale for this change `user-guide/latest/` is currently the unreleased docs built from main, so there is no stable URL for the newest release. This switches to the convention Apache Spark and Apache Iceberg use: | URL | Content | | -------------------- | ----------------------------------------- | | `user-guide/latest/` | The newest release (currently 1.1) | | `user-guide/dev/` | The development snapshot, built from main | | `user-guide/1.1/` | Each release, pinned (as today) | **We do not guarantee stable docs URLs between releases.** Only the versioned URLs (`user-guide/1.1/...`) are permanent. Pages under `latest/` and `dev/` can be added, renamed, moved or removed from one release to the next, so a deep link into either may stop working when the content moves. Links that must not change should use a versioned URL. This PR does not add redirects to keep old `latest/` or `dev/` page URLs working, and review comments asking for cross-release URL stability are out of scope. The guarantee is only that `latest/` always serves the newest release, and the user guide index says so. Expected consequences: existing links to `/user-guide/latest/...` will show 1.1 content, and pages that exist only on main (for example the consolidated `parquet.html` and `iceberg.html`) will 404 under `latest/` until the next release ships. ## What changes are included in this PR? - `docs/source/user-guide/latest` is renamed to `docs/source/user-guide/dev`, and all references are updated. This is a mechanical rename. The release branches keep whatever name they were cut with, and `generate-versions.py` now detects the directory instead of switching on the version number. - `generate-versions.py` builds the main-branch guide as `dev` and, after Sphinx runs, copies the newest release's built HTML to `user-guide/latest`. It is a copy, not a symlink, because the site is published by rsync into `asf-site`. The release version is two constants at the top of the file, so promoting a release also moves `latest`. - The five `user-guide/latest/...` redirects in `conf.py` are removed. They covered URLs from the old dev tree, and 1.1 has real pages at those paths. - The user guide index, `docs/README.md`, the release process and the backporting guide document the new layout and what is and is not guaranteed. ## How are these changes tested? The docs build was not run end to end (it clones the release branches and runs five Maven profiles). Checked instead: - All relative links to `user-guide/dev/` in the markdown sources resolve to existing files. - `get_user_guide_dir` and `alias_latest` were run against a fake tree. - Prettier passes on the changed markdown. Please check the preview or the first `main` publish: `user-guide/latest/`, `user-guide/dev/` and `user-guide/1.1/` should all render, and the sidebar and in-page links should work from each. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
