Enhance Versioning Support Documentation

[jabellard]

What documentation would you like to be added

A dedicated Version Support Policy & Version Skew Policy page, adopting the proven documentation pattern established by the Kubernetes project in its Releases section — specifically the Version Skew Policy page.

As Karmada matures, its documentation should reflect the same rigor and structure that the upstream Kubernetes project has established over years of community feedback. The Kubernetes releases section provides a clear model: a top-level area with dedicated pages for the release cycle, patch releases, and version skew policy. Karmada should adopt this proven pattern to give operators the same level of clarity they already rely on in Kubernetes.

This page would consolidate and clearly present:

1. Supported Versions — Which Karmada minor releases are currently maintained and for how long.
2. Component Version Skew Policy — The maximum allowed version differences between Karmada control plane components (karmada-controller-manager, karmada-scheduler, karmada-webhook, karmada-agent, etc.).
3. Member Cluster Compatibility — The supported Kubernetes version range for member clusters joining a given Karmada release.
4. Supported Upgrade Order — The prescribed sequence for upgrading Karmada components (sequential minor version upgrades only, no skipping).

Why do you think this document is needed

Today, the information above is scattered across at least four separate pages:

Information	Current location
Release support window	docs/releases.md
Kubernetes version compatibility matrix	docs/administrator/compatibility/compatibility.md
Upgrade sequencing and breaking-change policy	docs/administrator/upgrading/README.md and how-to-upgrade.md
API version skew behavior between control plane and member clusters	docs/troubleshooting/trouble-shooting.md

This fragmentation creates real problems:

• Operators planning upgrades have to piece together information from four pages to answer a simple question like "I'm on Karmada v1.14 with member clusters running Kubernetes v1.25 — can I upgrade to Karmada v1.16, and will my clusters still be compatible?"
• New adopters evaluating Karmada can't quickly determine what Kubernetes versions they need to run, or how long a given Karmada release will be supported. This is often one of the first questions platform teams need answered.
• Kubernetes has set the precedent. Operators managing multi-cluster environments with Karmada are already familiar with how the Kubernetes project structures its releases documentation — with dedicated pages for version skew policy, patch releases, and release cycles. They expect the same clarity from Karmada. Adopting this proven pattern signals project maturity and reduces the learning curve for teams already operating Kubernetes at scale.

A single, authoritative page — modeled after Kubernetes' version skew policy — would make Karmada's versioning story much easier to understand at a glance, reduce support questions, and align Karmada's documentation with the standards operators already trust from the broader Kubernetes ecosystem.

Where do you think the document should be placed

The document should be placed alongside the existing releases page, accessible from the top-level navigation — mirroring how the Kubernetes project organizes its Releases section with dedicated sub-pages for version skew policy, patch releases, and release cycles.

Suggested location: docs/releases/version-skew-policy.md (or as a sibling to docs/releases.md depending on the site's sidebar structure).

Alternatively, it could be added as a dedicated section within docs/releases.md, though a standalone page would be easier to link to from upgrade guides, compatibility docs, and external references.

Prior art

The Kubernetes project's releases documentation structure is the direct inspiration:

• kubernetes.io/releases/ — Top-level releases overview
• kubernetes.io/releases/version-skew-policy/ — Dedicated version skew policy
• kubernetes.io/releases/patch-releases/ — Patch release cadence and support

This structure has been validated by years of operator feedback in the Kubernetes community. As a CNCF project that extends Kubernetes, Karmada benefits from adopting the same documentation patterns that its users already know and trust.

[jabellard]

/cc @RainbowMango @zhzhuang-zju

[RainbowMango]

LGTM

[zhzhuang-zju]

Thanks, Joe, it makes sense to me. I'm glad you brought this up.

[SD-13]

Hey @jabellard , I would like to work on this enhancement. Though I am new to this project, it sounds doable. Thanks!
cc: @RainbowMango @zhzhuang-zju

[KanchanBorole]

Hi @jabellard ,

I'd be interested in contributing to this issue if it's still available. I've started looking into the existing documentation and researching the proposed changes.

Please let me know.

Thanks!

[jabellard]

Hey @KanchanBorole @SD-13 thanks for willing to help with this. I'd greatly appreciate your help here. Please let me know if you're still interested and I can break down this initiative into concrete tasks.

[KanchanBorole]

Hi @jabellard , Thank you for the response. Yes, I'm definitely interested in helping with this initiative.

The proposed Version Support Policy & Version Skew Policy documentation looks valuable for improving the operator experience and aligning Karmada's documentation with Kubernetes standards.

I'd appreciate it if you could break the work into concrete tasks or suggest a good starting point. Looking forward to contributing.

[SD-13]

Hey @KanchanBorole @SD-13 thanks for willing to help with this. I'd greatly appreciate your help here. Please let me know if you're still interested and I can break down this initiative into concrete tasks.

Yes @jabellard , I would be happy to help. Breaking it down into tasks would be helpful. Thanks!