Repository navigation
docs: maturity criteria, support policy and Preview banners (PR 7a of REORG-PLAN) - #500
Conversation
Add reference/maturity-and-lifecycle.md: the five Stable criteria, where each path stands (P6 on Kubernetes is the first target), the support policy for Legacy paths and the removal conditions. Add Preview banners to the deploy READMEs, advertise the tracking issue in the README, put the support rules in the migration guide and record the answered questions in REORG-PLAN. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
ingpaolodettori-dev
left a comment
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Summary
Docs only. Records the Stable criteria, the per-path status, the Legacy support policy and the removal conditions, and adds Preview banners to the four P6/P4 deploy pages. I checked the factual claims against main 08eb2a9:
- Knative images keep building:
build.yamlstill buildsmoca-sandboxandecho-targetfromdeploy/knative. Dependabot covers actions, npm, docker and gomod. - Single VM, no Redis persistence by default:
setup-vm.shstart_redisrunssh-rediswith no volume, by design, and the VM README's "Reboots" section says the same. - P4 limits: these match
P4-ON-P6.md"Limits": #277, #274, #338 and no grant binding. - Links: the new anchors (
#maturity-labels-and-banners,#support-for-legacy-paths) exist, and #490 is open.
I could not verify that k8s-e2e is not a required check, because this token can't read branch protection.
On the "interpretation to confirm": as written, the removal rule needs no one to object on #490, while the migration guide and ADR-0041 still say removal waits until the remaining users "have confirmed migration". See the comment on migrating-from-knative.md:175.
Author: pdettori (MEMBER — maintainer)
Areas reviewed: Docs
Agent/IDE config (.claude/.vscode): none
Commits: 1 commit, all signed-off: yes
CI status: passing (15/15)
| update. The full policy is in [Maturity and lifecycle](reference/maturity-and-lifecycle.md#support-for-legacy-paths). | ||
| - If you run the control plane on the deprecated K8s path during the window, #248's | ||
| namespace-collocation consideration still applies to it, unchanged by the deprecation. | ||
| - Removal happens no earlier than end of October 2026 and only once the remaining users have |
There was a problem hiding this comment.
suggestion: This bullet still uses the opt-in rule: removal waits "only once the remaining users have migrated", and users should "tell us when you have moved". maturity-and-lifecycle.md § Removal now uses the opt-out rule instead: the removal PR "merges only if no one there has said they still depend on the path". It also adds the archetype A/C condition, which this bullet doesn't mention. Since this PR already edits this section, suggest aligning the bullet with the policy page (or linking #removal), so the two pages give the same condition. ADR-0041 also says "confirmed migration"; the policy page could note that it records how that condition is now applied.
| | **P6 on Kubernetes** | Preview | **First target for Stable.** (1) No release names it yet. (2) A `k8s-e2e` job runs on `main`, but it is not a required check until it has passed ten consecutive runs. (3) Not yet: no upgrade or Redis backup guide. (4) Idle workspace reclaim is silent (#338), and async/cron have no P6 equivalent. (5) Not yet | | ||
| | Single VM | Preview | Production-oriented, but Redis has no persistence by default (a reboot may lose sessions), there is no upgrade or backup guide and no end-to-end CI. A later candidate | | ||
| | Docker Compose | Preview | A trial path by design; it will not be promoted | | ||
| | P4 microVM tier | Preview | Open limits (#277 no guest network, #274 fresh VM per call, #338 silent reset, no per-user binding); its CI gate is manual only | |
There was a problem hiding this comment.
nit: "its CI gate is manual only" undersells it. The hypervisor-free §8 gates run on every PR and push (ci.yml job microvm-gates). Only the gates that need /dev/kvm and a golden snapshot are manual (microvm-kvm-gates.yml, workflow_dispatch). Suggest: "its KVM gates run only manually".
| 1. ~~What do "Preview" and "Stable" mean?~~ **Answered 2026-10-13:** five criteria (a release names the path, required end-to-end CI, documented upgrade and recovery, no silent data-loss limits, a stated change policy); P6 on Kubernetes is the first target; Compose never promotes; a release naming P6 as the supported runtime (Preview) comes first. See `docs/reference/maturity-and-lifecycle.md`. | ||
| 2. **Removal date/version:** answered in part on 2026-10-13: the removal PR does not merge before the end of October 2026, is announced on #490 first, and merges only if no one there says they still depend on the path. No further date, version or notice period is committed. | ||
| 3. ~~Support semantics during the window~~ **Answered 2026-10-13:** fixes land on `main` only (no release branches or backports); "breakage" means a regression or a dependency/base-image break; mock-based CI and unit tests keep running and the Knative images keep building; no live Knative end-to-end job; support ends when the removal PR merges. See `docs/reference/maturity-and-lifecycle.md`. | ||
| 4. **Environments:** is P4 in-cluster (Kata/gVisor) planned? Is Compose trial-only permanently? Any macOS/Windows path for P4? Is `deploy/vm` the supported production path (migration guide says so; its own README has no label)? |
There was a problem hiding this comment.
nit: This PR answers two parts of Q4, which still reads as fully open. "Is Compose trial-only permanently?" is now yes ("will not be promoted"), and "deploy/vm … its own README has no label" is fixed by the new Preview banner. Suggest marking Q4 as partly answered, like Q2.
Summary
Records the maintainer's decisions of 2026-10-13 on open questions 1 and 3 (and the part of 2 that is settled). Docs only. Based on
mainafter #498.docs/reference/maturity-and-lifecycle.md(new): the Stable / Preview / Legacy labels; the five criteria for Stable (a release names the path, required end-to-end CI, documented upgrade and recovery, no silent data-loss limits, a stated change policy); where each path stands against them, with P6 on Kubernetes as the first target; the support policy for Legacy paths (fixes onmainonly, what "breakage" means, what CI keeps running, support ends at the removal PR); and the removal conditions.deploy/k8s,deploy/vm,deploy/composeanddeploy/microvm/P4-ON-P6.md(the open item from the original audit). Compose is labelled "trial only, will not be promoted".docs/index.md: links the new page.REORG-PLAN.md: questions 1 and 3 marked answered, 2 partly.Interpretation to confirm
"Lead time before the removal PR: until end of October 2026" is recorded as: the removal PR does not merge before the end of October 2026, is announced on #490 first, and merges only if no one there has said they still depend on the path. No notice period in days is committed. Say if you meant something different.
Not done
Cutting the release whose notes name P6 as the supported runtime (Preview): that is a release action for the maintainer; draft notes are in the discussion thread, not in this PR. The Stable criteria for P6 on Kubernetes that still need work are listed in the new page: a required
k8s-e2echeck, upgrade and Redis backup docs, a change policy, and the silent-reset and async/cron limits.Verification
scripts/check-doc-links.pyreports 0 broken links over 174 files; Prettier run on changed files.make lintnot run locally; CI will.Assisted-By: Claude (Anthropic AI) noreply@anthropic.com