Skip to content

docs: add VERSIONING.md for release versioning and agent skew#741

Open
Yetkin Timocin (ytimocin) wants to merge 1 commit into
kubefleet-dev:mainfrom
ytimocin:docs/versioning-guide
Open

docs: add VERSIONING.md for release versioning and agent skew#741
Yetkin Timocin (ytimocin) wants to merge 1 commit into
kubefleet-dev:mainfrom
ytimocin:docs/versioning-guide

Conversation

@ytimocin

Copy link
Copy Markdown
Collaborator

Description of your changes

Adds VERSIONING.md, the versioning and upgrade policy document tracked under the Phase 1 release-process work in #693. It complements the support-window policy in SECURITY.md and the contribution conventions in CONTRIBUTING.md.

The document covers:

  • Versioning scheme — SemVer vMAJOR.MINOR.PATCH with -rc.N pre-releases (matching the tag validation in setup-release.yml), and the pre-1.0 0.y.z semantics (minors may break; patches are a deliberate backward-compatible commitment stricter than SemVer requires for 0.y.z).
  • Minor-vs-patch bump criteria for 0.x — a table for deciding when a change warrants a minor versus a patch.
  • Release cadence and supported versions — ~3-month minors, N/N-1 supported, deferring the authoritative statement to SECURITY.md.
  • Agent version skew — hub-agent and member-agent may differ by at most one minor in either direction. This is grounded in, and validated by, the three compatibility jobs already running in upgrade.yml (hub-agent-backward-compatibility, member-agent-backward-compatibility, full-backward-compatibility). The doc explicitly notes where this symmetric one-minor guarantee deliberately diverges from the asymmetric Kubernetes kubelet skew policy and why.
  • Recommended upgrade ordering — hub first, then members, mirroring the Kubernetes control-plane-first convention.
  • Cross-agent contracts — the Work/AppliedWork and InternalMemberCluster status contracts that must stay backward-compatible across a skew window.
  • API versioning — both v1 and v1beta1 are served for the placement and cluster groups (v1 the promoted surface, v1beta1 the storage version), deferring per-API lifecycle to the upstream Kubernetes API deprecation policy by convention, plus Helm-vs-raw-YAML CRD upgrade guidance.

Also adds a one-line pointer to VERSIONING.md from the README.

Maps to #693 Phase 1.

Refs #693

I have:

  • Associated this change with a known KubeFleet Issue (Bug, Feature, etc).
  • Run make reviewable to ensure this PR is ready for review. (No-op for this PR: no Go sources touched; docs/markdown CI covers the changed files.)

How has this code been tested

  • All relative links in VERSIONING.md were verified to resolve to real paths in the repo (SECURITY.md, CONTRIBUTING.md, .github/workflows/setup-release.yml, .github/workflows/upgrade.yml, test/upgrade/upgrade.sh, both chart templates/crds/ directories).
  • All external links return HTTP 200 (semver.org, the Kubernetes version-skew and API-deprecation policy pages).
  • Every factual claim was cross-checked against the source: the three compat jobs and paths-ignore/detect-noop scoping in upgrade.yml; the member-to-hub heartbeat path (member patches InternalMemberCluster status, hub mirrors to MemberCluster); the v1/v1beta1 served-and-storage settings in the CRD manifests; and the Helm templates/crds/ upgrade behavior.
  • The new file ends with a trailing newline per repo convention; markdown link-check CI will exercise the changes end-to-end.

Special notes for your reviewer

  • This is documentation only — no Go sources, workflows, or CRDs are modified.
  • The agent-skew guarantee is described as symmetric one-minor, which is intentionally stronger and simpler than the Kubernetes kubelet rule; the doc calls this out so Kubernetes-literate readers are not surprised. If maintainers prefer a more conservative (asymmetric, hub-first-only) statement, that is a one-paragraph change.

Document the versioning scheme (SemVer with -rc pre-releases and 0.x
semantics), release cadence and support window, the 0.x minor-vs-patch
bump criteria, the supported hub/member agent version skew (symmetric
one-minor, validated by the upgrade compatibility suite), the recommended
hub-first upgrade ordering, the Work/AppliedWork and InternalMemberCluster
cross-agent contracts, and CRD API versioning. Add a pointer from the
README.

Refs kubefleet-dev#693

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Yetkin Timocin <ytimocin@microsoft.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant