jchong9 opened a new issue, #436: URL: https://github.com/apache/superset-kubernetes-operator/issues/436
**Problem / use case** Currently, the documentation only reflects the latest state of the main branch of the repository. As there are already three released versions (0.1, 0.2, and 0.3), the live documentation often includes unreleased changes, new configuration flags, or features that do not apply to any currently installed user versions. This leads to broken setups and confusion for users running stable releases. **Proposed behavior** We should update the documentation and release process to persist versioned snapshots for each released version, allowing users to select their exact version from a dropdown. To achieve this, we can use [mike](https://github.com/jimporter/mike?tab=readme-ov-file) (the standard version manager for MkDocs-based ecosystems) alongside a proposed CI/CD release workflow: ``` IF current branch is main: -> Deploy documentation version as main -> Set latest as the default version redirect on gh-pages ELSE IF current ref is a release tag (starting with v): -> Extract the version string (stripping the v prefix) -> Deploy documentation for this specific version tag -> IF the version string does NOT contain -rc (so its a release): -> Deploy documentation again with the stable alias (and update aliases) ``` **Implementation Paths & Considerations** Depending on how we want to tool this, we are looking at two potential approaches: 1. Option A (Standard MkDocs + mike): Keep MkDocs, initialize mike to manage version subdirectories (/0.3/, /dev/, etc.), and set up the automated CI workflow. 2. Option B (Zensical Migration + mike fork): As part of this effort, migrate from MkDocs to Zensical. Because Zensical reads mkdocs.yml natively, the code change is minimal (swapping the build/serve commands). However, because we use --require-hashes in our dependency management, adopting Zensical requires using the Zensical-compatible mike fork and splitting the installation into a separate two-step process in CI. **Questions for Next Steps** Before diving into a PR, I wanted to run a few approach details: - Transitioning gh-pages & Root Docs: mike structures builds into isolated subdirectories on the deployment branch. Since our current docs live flat at the root, we'll need to clean those up during the switch. Do you have a preference for how we handle this initial cleanup? - Backfilling Old Releases (0.1, 0.2, 0.3): Future releases can be automated via CI, but we'll need to check out the old tags and backfill them. What is the preferred way to handle permissions or execute this initial backfill? - MkDocs vs. Zensical: Our group is leaning toward Zensical for this migration since MkDocs will no longer be maintained in 2027. Do you have any preferences or concerns regarding migrating to Zensical as part of this versioning effort? -- 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]
