villebro commented on issue #436: URL: https://github.com/apache/superset-kubernetes-operator/issues/436#issuecomment-6172184559
Thanks for writing this up, I agree with the direction. A few wishes before a PR: **Zensical, without depending on its roadmap** Given where MkDocs 2.0 is heading, I don't want to deepen our MkDocs integration, so Option A is out (upstream mike is an MkDocs plugin). Moving to Zensical makes sense: our docs use no MkDocs plugins, so it should mostly be a dependency and command swap. Ideally that lands as its own PR before the versioning work. For versioning, though, I'd rather not plan around Zensical's native support. It's still an [open proposal](https://github.com/zensical/backlog/issues/45) with no activity since it was filed. The [squidfunk/mike](https://github.com/squidfunk/mike) fork is explicitly transitional: git-only, bug fixes only, and maintained only until native versioning arrives. If that takes a while, we'd be carrying a frozen, git-installed dependency indefinitely. The theme's version selector only reads a static `versions.json` next to the version directories. So I'd prefer a small script under `scripts/` that builds a version into its directory, updates `versions.json` and the `latest` alias, and commits to `gh-pages`. That keeps our hash-pinned requirements as they are, gives us full control of the `gh-pages` root (which the unversioned section below needs), and stays compatible with the selector. If native versioning ships later, we can evaluate it then. If the script turns out to reimplement too much of mike, the fork is an acceptable fallback, pinned to a release and called only from that same script. **Versioned and unversioned sections** Not everything should be versioned. Pages that describe the project rather than a release should exist once and track `main`: - **Unversioned:** Home, Releases (changelog), Downloads, Contributing (setup, guidelines, releasing), and Security. - **Versioned:** Getting Started, User Guide, Architecture, API Reference. Security scans and vulnerability reports usually target the repo's current state, so I'd keep a single threat model rather than one per release. As part of this, let's add a note at the top of the security page saying it reflects the current `main` branch and broadly applies to released versions, with the Security sections in the changelog covering release-specific changes. Roughly what I have in mind: - The root site is built from `main` with only the unversioned pages. Versioned docs get one directory per minor release (`0.3/`), plus `main` for unreleased docs and a `latest` alias. - `latest`, the newest final release, is the default landing version, not `main`. That's the confusion this issue is about. Non-latest versions get a banner. - Nav entries cross-link the two sections with absolute URLs, so it still feels like one site. Zensical 0.0.70 added `exclude_docs`/`not_in_nav`, so both builds can probably share the existing `docs/` tree with two configs. - Track minors, not patches (`0.3.1` overwrites `0.3`), and deploy only on final tags after the vote, never on RCs. **On your questions** - *Root cleanup:* the new unversioned site replaces the root, so there's nothing to clean up by hand. The current `gh-deploy --force` would wipe the version directories, though, so the root deploy needs to change. Existing deep links (e.g. `/user-guide/configuration/`) are baked into released READMEs and charts, so let's keep them working with redirect stubs to `latest`. - *Backfill:* a `workflow_dispatch` that takes a tag and runs the same deploy path as a release. Nobody needs manual push access to `gh-pages`, and the backfill exercises the real pipeline. I'd backfill 0.3 (and maybe 0.2). Old tags predate the split, so expect a small shim to drop the unversioned pages from their builds. - *MkDocs vs. Zensical:* Zensical for building, but versioning shouldn't depend on Zensical's roadmap. See above. -- 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]
