Skip to content

Kep 5073 lifecycle tag linting#4

Open
aaron-prindle wants to merge 1 commit intomasterfrom
kep-5073-lifecycle-tag-linting
Open

Kep 5073 lifecycle tag linting#4
aaron-prindle wants to merge 1 commit intomasterfrom
kep-5073-lifecycle-tag-linting

Conversation

@aaron-prindle
Copy link
Copy Markdown
Owner

  • One-line PR description:
  • Issue link:
  • Other comments:

@aaron-prindle aaron-prindle force-pushed the kep-5073-lifecycle-tag-linting branch from 71ac1dd to 078e6fb Compare April 15, 2026 21:04
Adds concrete documentation for how +k8s:alpha(since: "1.N") and
+k8s:beta(since: "1.N") declarative validation lifecycle tags are
enforced, graduated, and owned. Touches six sections of the KEP:

- Solution: Lifecycle Tags — corrects the tag syntax (quoted
  since: string, no v prefix), documents mandatory since: in
  staging/src/k8s.io/api/**, records the community-driven
  ownership model with subproject leads as escalation path, and
  calls out the intentional format divergence from the older
  +k8s:prerelease-lifecycle-gen:introduced=1.N marker.

- Execution & Authority Logic — adds a "two stability axes"
  note distinguishing TagStabilityLevel (is the +k8s:minimum
  tag definition Alpha/Beta/Stable?) from ValidationStabilityLevel
  (is this specific application of the tag wrapped in +k8s:alpha
  or +k8s:beta?). The runtime enforcement table reads the
  validation-instance axis; the lint rules read both. This
  distinction is the main comprehension hazard contributors hit
  on first encounter.

- Linter — new "Lifecycle Tag Lint Rules" subsection
  enumerating every lint rule (existing + new in 1.36 and 1.37)
  with its enforcement home, rationale, and error behavior.
  Two rules live in kube-api-linter (alphaBetaPrefix stays where
  it is; conflictingmarkers with the
  declarative_validation_lifecycle_alpha_vs_beta conflict set
  enforces alpha ⊥ beta per field, landing as a config-only
  change in 1.36). The rest live in validation-gen's own
  internal lint harness:
    * lifecycleSinceRequired (1.37) rejects wrappers without
      since: in k8s.io/api/** packages
    * lifecycleStaleSince (1.37) warns at N+1 and errors at N+2
      past the since: value for alpha (shifted by one for beta),
      supporting per-field exemption via
      // +k8s:validation-lifecycle-exempt=<reason>
  All enforcement is generation/lint time — deliberately not
  runtime, to avoid the #127249 cautionary tale where a binary
  version bump silently changed API availability.

- Rollout Strategy Phase 2 — documents that lifecycle lint rules
  land across 1.36 (conflictingmarkers config only) and 1.37
  (lifecycleSinceRequired + lifecycleStaleSince in
  validation-gen, plus the warning pipeline that enables the
  non-blocking stale-since reminder).

- Lifecycle: Promotion Process (Continuous) — rewrites the
  three-step flow with the state machine diagram, the entry
  rules table (including the legacy fast-path carveout for
  pre-v1.36 fields migrating from handwritten validation with
  existing soak history), the soak definition and prerequisites
  for each graduation step with resource-level attribution
  accepted, per-step ownership language, and an explicit
  Non-goals block rejecting runtime enforcement, auto-graduation,
  metric-driven enforcement in-lint, and cross-version
  consistency linting.

- Example Walkthrough — fixes the (since:v1.39) typos (bare
  form with v prefix) to match the real (since: "1.39") quoted
  format that validation-gen's parser actually accepts.

- Graduation Criteria — adds a clarifying paragraph that this
  section governs tag *definition* graduation (the
  TagStabilityLevel axis for e.g. "is +k8s:minimum a Beta tag or
  a Stable tag?") and points at the per-rule Lifecycle Promotion
  Process above for validation-instance graduation. These are
  two independent axes and contributors reading the KEP for the
  first time conflate them.

The accompanying implementation lives in kubernetes/kubernetes
branch kep-5073-lifecycle-tag-linting (to be opened as a PR
separately). It adds:
- hack/kube-api-linter config for conflictingmarkers alpha ⊥ beta
- validation-gen/lint warning pipeline
- validation-gen/lint lifecycleSinceRequired rule + 9 unit tests
- validation-gen/lint lifecycleStaleSince rule (error + warning
  variants) + 21 unit tests
- validation-gen --current-release flag with fallback text-read
  of staging/src/k8s.io/component-base/version/base.go
- staging/src/k8s.io/code-generator/cmd/validation-gen/docs/lifecycle-tags.md
  reference doc for contributors
- hack/update-codegen.sh wiring to pass --current-release
  explicitly in every presubmit run
@aaron-prindle aaron-prindle force-pushed the kep-5073-lifecycle-tag-linting branch from 078e6fb to 48af00d Compare April 30, 2026 08:07
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