Repository navigation
feat(featuregate): version-keyed feature gates with readiness-gated alpha opt-ins (#1275) - #1482
Open
leninmehedy wants to merge 1 commit into
Open
leninmehedy wants to merge 1 commit into
leninmehedy wants to merge 1 commit into
Conversation
This was referenced Nov 21, 2026
leninmehedy
force-pushed
the
01275-feature-gate-system
branch
5 times, most recently
from
November 21, 2026 00:49
f91fe9a to
7eb5804
Compare
leninmehedy
force-pushed
the
01275-feature-gate-system
branch
from
November 21, 2026 00:58
7eb5804 to
7619e92
Compare
…lpha opt-ins (#1275) Introduce solo-provisioner's feature-gate system, a thin adapter over github.com/automa-saga/gatekit that lets a behaviour or contract change land behind an off-by-default gate instead of forcing every change to stay backward-compatible. Layer 1 of epic #1275 (gate + maturity); Layer 2 (finalize, state-backed activation axis, gated migrations) is out of scope. Core model (internal/featuregate) - A registry keys every gated behaviour by an activation version (ActiveFrom) and tags it with a maturity (Alpha/Beta/GA). CurrentActivationVersion is the in-force version (1, the GA floor); SupportWindow is the single source of the window W. - Two axes: a feature is on when the last spec with ActiveFrom <= current resolves on; Alpha needs an operator opt-in, Beta/GA follow the version axis alone. Readiness-gated opt-ins - An operator opt-in (--experimental or SOLO_PROVISIONER_ENABLE_<FEATURE>) enables an alpha only when its spec is ready (Default:true). An unfinished Alpha,Default:false feature is dormant: no opt-in can turn it on, yet gate.Enabled(f) still compiles and returns false, so a feature can be merged incrementally with no risk of exposing a half-done path. --experimental is command-scoped and shares one gate with business code, so command availability and in-code behaviour are one decision. CLI - `solo-provisioner feature list` inspects the catalog (maturity, ActiveFrom, enabled, opt-in env var) with filters; read-only, runs unprivileged. - common.GateFeature / GateFeatureFlag gate a command or a single flag by maturity: an alpha is hidden from --help and refused unless opted in; a persistent flag is gated on PersistentPreRunE so inheriting subcommands are covered too. A golden --help surface test pins the visible command/flag surface so accidental exposure can't merge. - `kube cluster upgrade` moved onto the KubeClusterUpgrade alpha gate. Lints (ordinary CI, pure-Go) - Removal lint, baseline lint (against testdata/baseline_registry.json, regenerated only at release with -update-baseline), and a dev-gate-window warning. Docs - docs/dev/feature-gates.md: the model, defining and promoting a feature, the opt-in surfaces, development vs compatibility gates, and the lints. Replaces the bespoke --experimental command gate (GateExperimental) and moves the whole system onto gatekit v0.7.0. Signed-off-by: Lenin Mehedy <lenin.mehedy@hashgraph.com>
leninmehedy
force-pushed
the
01275-feature-gate-system
branch
from
November 21, 2026 01:02
7619e92 to
095027e
Compare
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.
What this introduces
Solo-provisioner's feature-gate system — a thin adapter over
github.com/automa-saga/gatekitthat lets a behaviour or contract change land behind an off-by-default gate instead of forcing every change to stay backward-compatible. This is Layer 1 of epic #1275 (gate + maturity).The model
A gate sits on one axis and carries two independent labels — keep them separate:
ActiveFrom): a coordination counter, not a per-feature counter. You don't bump it to add a feature — development gates all live at the current version. Only a compatibility gate ever advances it, so it may stay at1forever.Alpha/Beta/GA/Deprecated): how ready for users.Alphaneeds an opt-in;Beta/GAride the version axis.finalize, Layer 2).Maturity and gate kind are orthogonal. For an
Alphaspec,Defaultis the readiness switch:Defaultfalsetrue--experimentalor the env varAn opt-in enables an alpha only when it's ready. A dormant
Alpha, Default: falsefeature is unreachable by any opt-in, yetgate.Enabled(f)still compiles and returnsfalse— so a feature merges incrementally with no risk of exposing a half-done path. This adopts gatekit's nativeWithExperimentalsemantics (which honourDefault) while keeping the opt-in command-scoped and sharing one gate between a command and its business code.Deciding how to define a feature
ActiveFromMaturityDefault1)Alphafalse1)Alphatrue--experimental/ env1)Betatrue--experimental/ env1)GAtrueAlpha→GADeprecatedelsebranchThe full decision tree is in
docs/dev/feature-gates.md.Feature lifecycle — define and promote
registry.go{ActiveFrom: 1, Default: false, Maturity: Alpha}gate.Enabled(f)returnsfalse{ActiveFrom: 1, Default: true, Maturity: Alpha}--experimental/ envDefault: false → true{ActiveFrom: 1, Default: true, Maturity: GA}Alpha → GAin placeelsebranchDeprecatedExample — define a dormant feature
features.go:registry.go:business code:
Example — promote it
1. Ready to dogfood — flip
Default:Now
kube cluster upgrade --experimental(orSOLO_PROVISIONER_ENABLE_KUBE_CLUSTER_UPGRADE=1) runs it.2. GA — graduate the maturity in place:
Now it's on for everyone; drop the command's
--experimentalgate.What's in the PR
internal/featuregate/— the catalog (registry.go), the two-axis gate (gate.go), readiness-aware env opt-ins (env.go), feature constants +CurrentActivationVersion+SupportWindow(features.go).solo-provisioner feature list(cmd/cli/commands/feature/) — inspects the catalog (maturity,ActiveFrom, enabled, opt-in env var) with filters; read-only, runs unprivileged.cmd/cli/commands/common/feature_gate.go) —GateFeature/GateFeatureFlaghide and label by maturity and refuse unless opted in; a persistent flag is gated onPersistentPreRunEso inheriting subcommands are covered.GateExperimental(bespoke) is removed.--helpsurface test — pins the visible command/flag surface so accidental exposure of an alpha can't merge silently.kube cluster upgrade— moved onto theKubeClusterUpgradealpha gate.lint_test.go) — removal lint, baseline lint (vstestdata/baseline_registry.json), dev-gate-window warning. Pure-Go, run in ordinary CI.docs/dev/feature-gates.md— the full dev guide.go.mod/go.sumbump.Opt-in surfaces (all readiness-aware)
--experimental— hidden, command-scoped flag; enables that command's ready feature. Preferred undersudo, which strips env vars.SOLO_PROVISIONER_ENABLE_<FEATURE>=1— per-feature env var; the exact name is printed byfeature list.Options.Overrides— internal raw seam for tests / programmatic forcing; bypasses readiness. Not an operator surface.What to review
requireFeatureEnabled+ExperimentalReady(gate.go,feature_gate.go): a ready alpha is enabled by an opt-in; a dormant one is refused with a distinct message.featuregate.Gate(ctx)(not its ownNewDefault()).envFeatureRequestskeeps gatekit's strict unknown/malformed behaviour.Testing
go test ./internal/featuregate/... ./cmd/cli/commands/...andtask lintpass. These paths are pure-Go (no Linux-only deps), so they run in normal CI; the full suite still needs the UTM VM per repo rules.Out of scope