feat(lifecycle): lifecycle: block — maturity, deprecation, compatibility, and komposer acceptance - #263
Merged
Merged
Conversation
…ity, and komposer acceptance Adds a top-level lifecycle: block to every Katalog and Komposer file: - lifecycle.maturity: alpha | beta | stable | deprecated — advisory signal; ork validate warns for pre-stable imports - lifecycle.deprecation: message, migratedTo, timeline — surfaced at push, validate, inspect, pull, and runtime startup; deprecated Katalogs always block ork run unless imported via a Komposer with lifecycle.accept.patterns - lifecycle.compatibility: kubernetes/orkestra semver ranges; ork validate rejects patterns outside the declared range - lifecycle.accept.patterns (Komposer-only): acknowledges deprecated or pre-stable imports by name; optional version scoping - policy.lifecycle.minMaturity: platform floor; imports below the declared maturity level are errors at validate time metadata.deprecation removed; lifecycle.deprecation is the canonical location. Katalog-level accept removed entirely — acceptance belongs on the Komposer. Registry guide steps renumbered: hooks→09, typed-komposer→10, ork-action→11, deprecation→12; new steps 13–16 cover deprecation-accept, lifecycle-maturity, lifecycle-compatibility, and komposer-accept. Schema evolution docs updated with a third layer (Gateway API / serve.fields.values). lifecycle: concepts page and registry guide corrected and expanded.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lifecycle in Orkestra has always existed as a convention — deprecation lived in
metadata, maturity was implied by version numbers, compatibility was communicated in READMEs. This PR makes it a first-class citizen.A new top-level
lifecycle:block now sits alongsidemetadata,spec, andgatewayon every Katalog. It is the contract the pattern author makes with the platform and with consumers:Maturity is a signal —
alpha,beta,stable,deprecated. It appears inork inspect, warns atork validate, and can be enforced by a platform floor (policy.lifecycle.minMaturity). A pattern that skips it is treated as stable. A pattern that declaresdeprecatedwithout a deprecation block gets a warning, not a pass.Deprecation is enforced. The block travels with the artifact into OCI annotations, surfaces at every touchpoint (
ork push,ork validate,ork inspect,ork pull), and blocksork runwhen the state is active. The author sees exactly what their consumers will see — before the artifact is uploaded.The acceptance model is deliberate: a deprecated Katalog cannot self-accept. The field doesn't exist on the Katalog type. Acceptance belongs on the Komposer — the consumer making a traceable, reviewable decision about what they are knowingly importing:
Compatibility gives pattern authors a way to declare verified version ranges and gives the platform a way to reject patterns that claim to work on Kubernetes 1.24 when the cluster is already on 1.31.
Policy keeps it extensible. Rather than flattening a maturity floor directly under
policy:, it lives atpolicy.lifecycle.minMaturity— making room for future security policy, registry policy, and user-defined policy can grow alongside it without forcing a schema break.metadata.deprecationis removed. The oldaccept: { beforeEol, eol }struct is gone. Registry guide get additional lifecycle story as runnable examples.