ADR-029: Versioned documentation with mike

Category: development Provenance: human

Decision

Maintain multiple documentation versions using mike. Previous versions remain available on GitHub Pages for users running older operator versions.

Rationale

Users running older operator versions need documentation matching their version. Breaking changes in CRDs or APIs require version-specific documentation. Mike integrates with MkDocs to provide version switcher in UI. All versions remain accessible at predictable URLs. Supports gradual rollouts where different teams run different versions. Historical documentation valuable for troubleshooting and migrations.

Agent Instructions

Use mike to manage documentation versions. Deploy new versions with 'mike deploy '. Set default version with 'mike set-default '. Never delete old documentation versions - users need docs for the version they're running. Version selector in docs allows users to switch between versions.

Rejected Alternatives

Only publish latest documentation

Users on older versions have no documentation. Breaking changes leave them without guidance.

Separate git branches for each version

Harder to maintain, no version switcher UI, inconsistent navigation between versions.