featuregate: Add deprecated Stage and to/from versions

Fixes 2 out of the 3 tasks in open-telemetry#7043

Signed-off-by: Bogdan Drutu <[email protected]>

Author: bogdandrutu

.chloggen/deprecateremoval.yaml

@@ -0,0 +1,11 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: featuregate
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Deprecate Gate.RemovalVersion and WithRegisterRemovalVersion in favor of ToVersion.
+
+# One or more tracking issues or pull requests related to the change
+issues: [7043]

.chloggen/featuregatetasks.yaml

@@ -0,0 +1,11 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: featuregate
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add a new Deprecated stage for feature gates, when features are abandoned.
+
+# One or more tracking issues or pull requests related to the change
+issues: [7043]

.chloggen/tofromversion.yaml

@@ -0,0 +1,11 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: featuregate
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add concept of gate lifetime, [fromVersion, toVersion].
+
+# One or more tracking issues or pull requests related to the change
+issues: [7043]

confmap/resolver.go

@@ -50,7 +50,7 @@ var (
 var _ = featuregate.GlobalRegistry().MustRegister(
 	"confmap.expandEnabled",
 	featuregate.StageStable,
-	featuregate.WithRegisterRemovalVersion("v0.75.0"),
+	featuregate.WithRegisterToVersion("v0.75.0"),
 	featuregate.WithRegisterDescription("controls whether expanding embedded external config providers URIs"))
 
 // Resolver resolves a configuration as a Conf.

featuregate/README.md

@@ -18,10 +18,11 @@ Once a `Gate` has been marked as `Stable`, it must have a `RemovalVersion` set.
 ```go
 var myFeatureGate = featuregate.GlobalRegistry().MustRegister(
 	"namespaced.uniqueIdentifier",
-	featuregate.Stable, 
+	featuregate.Stable,
+    featuregate.WithRegisterFromVersion("v0.65.0")
 	featuregate.WithRegisterDescription("A brief description of what the gate controls"),
 	featuregate.WithRegisterReferenceURL("https://github.com/open-telemetry/opentelemetry-collector/issues/6167"),
-	featuregate.WithRegisterRemovalVersion("v0.70.0"))
+	featuregate.WithRegisterToVersion("v0.70.0"))
 ```
 
 The status of the gate may later be checked by interrogating the global 

featuregate/flag_test.go

@@ -110,7 +110,7 @@ func TestNewFlag(t *testing.T) {
 			reg := NewRegistry()
 			reg.MustRegister("alpha", StageAlpha)
 			reg.MustRegister("beta", StageBeta)
-			reg.MustRegister("stable", StageStable, WithRegisterRemovalVersion("1.0.0"))
+			reg.MustRegister("stable", StageStable, WithRegisterToVersion("1.0.0"))
 			v := NewFlag(reg)
 			if tt.expectedSetErr {
 				require.Error(t, v.Set(tt.input))

featuregate/gate.go

@@ -19,12 +19,13 @@ import "sync/atomic"
 // Gate is an immutable object that is owned by the Registry and represents an individual feature that
 // may be enabled or disabled based on the lifecycle state of the feature and CLI flags specified by the user.
 type Gate struct {
-	id             string
-	description    string
-	referenceURL   string
-	removalVersion string
-	stage          Stage
-	enabled        *atomic.Bool
+	id           string
+	description  string
+	referenceURL string
+	fromVersion  string
+	toVersion    string
+	stage        Stage
+	enabled      *atomic.Bool
 }
 
 // ID returns the id of the Gate.
@@ -52,7 +53,17 @@ func (g *Gate) ReferenceURL() string {
 	return g.referenceURL
 }
 
-// RemovalVersion returns the removal version information for Gate's in StageStable.
+// FromVersion returns the version information when the Gate's was added.
+func (g *Gate) FromVersion() string {
+	return g.fromVersion
+}
+
+// ToVersion returns the version information when Gate's in StageStable.
+func (g *Gate) ToVersion() string {
+	return g.toVersion
+}
+
+// Deprecated: [v0.76.0] use ToVersion().
 func (g *Gate) RemovalVersion() string {
-	return g.removalVersion
+	return g.ToVersion()
 }

featuregate/registry.go

@@ -62,11 +62,23 @@ func WithRegisterReferenceURL(url string) RegisterOption {
 	})
 }
 
-// WithRegisterRemovalVersion is used when the Gate is considered StageStable,
-// to inform users that referencing the gate is no longer needed.
-func WithRegisterRemovalVersion(version string) RegisterOption {
+// Deprecated: [v0.76.0] use WithRegisterToVersion.
+var WithRegisterRemovalVersion = WithRegisterToVersion
+
+// WithRegisterFromVersion is used to set the Gate "FromVersion".
+// The "FromVersion" contains the Collector release when a feature is introduced.
+func WithRegisterFromVersion(fromVersion string) RegisterOption {
+	return registerOptionFunc(func(g *Gate) {
+		g.fromVersion = fromVersion
+	})
+}
+
+// WithRegisterToVersion is used to set the Gate "ToVersion".
+// The "ToVersion", if not empty, contains the last Collector release in which you can still use a feature gate.
+// If the feature stage is either "Deprecated" or "Stable", the "ToVersion" is the Collector release when the feature is removed.
+func WithRegisterToVersion(toVersion string) RegisterOption {
 	return registerOptionFunc(func(g *Gate) {
-		g.removalVersion = version
+		g.toVersion = toVersion
 	})
 }
 
@@ -98,7 +110,7 @@ func (r *Registry) Register(id string, stage Stage, opts ...RegisterOption) (*Ga
 	default:
 		return nil, fmt.Errorf("unknown stage value %q for gate %q", stage, id)
 	}
-	if g.stage == StageStable && g.removalVersion == "" {
+	if g.stage == StageStable && g.toVersion == "" {
 		return nil, fmt.Errorf("no removal version set for stable gate %q", id)
 	}
 	if _, loaded := r.gates.LoadOrStore(id, g); loaded {

featuregate/registry_test.go

@@ -55,7 +55,7 @@ func TestRegistryApplyError(t *testing.T) {
 	assert.Error(t, r.Set("foo", true))
 	r.MustRegister("bar", StageAlpha)
 	assert.Error(t, r.Set("foo", true))
-	r.MustRegister("foo", StageStable, WithRegisterRemovalVersion("next"))
+	r.MustRegister("foo", StageStable, WithRegisterToVersion("next"))
 	assert.Error(t, r.Set("foo", true))
 }
 
@@ -90,7 +90,7 @@ func TestRegisterGateLifecycle(t *testing.T) {
 			opts: []RegisterOption{
 				WithRegisterDescription("test-gate"),
 				WithRegisterReferenceURL("http://example.com/issue/1"),
-				WithRegisterRemovalVersion(""),
+				WithRegisterToVersion(""),
 			},
 			enabled:   false,
 			shouldErr: false,
@@ -107,7 +107,7 @@ func TestRegisterGateLifecycle(t *testing.T) {
 			id:    "test-gate",
 			stage: StageStable,
 			opts: []RegisterOption{
-				WithRegisterRemovalVersion("next"),
+				WithRegisterToVersion("next"),
 			},
 			enabled:   true,
 			shouldErr: false,

featuregate/stage.go

@@ -29,10 +29,15 @@ const (
 	// The Gate will be enabled by default.
 	StageBeta
 	// StageStable is used when feature is permanently enabled and can not be disabled by a Gate.
-	// This value is used to provide feedback to the user that the gate will be removed in the next version.
+	// This value is used to provide feedback to the user that the gate will be removed in the next versions.
 	//
 	// The Gate will be enabled by default and will return an error if modified.
 	StageStable
+	// StageDeprecated is used when feature is permanently disabled and can not be enabled by a Gate.
+	// This value is used to provide feedback to the user that the gate will be removed in the next versions.
+	//
+	// The Gate will be disabled by default and will return an error if modified.
+	StageDeprecated
 )
 
 func (s Stage) String() string {
@@ -43,6 +48,8 @@ func (s Stage) String() string {
 		return "Beta"
 	case StageStable:
 		return "Stable"
+	case StageDeprecated:
+		return "Deprecated"
 	}
 	return "Unknown"
 }