featuregate: Add deprecated Stage and to/from versions

Fixes 2 out of the 3 tasks in #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/gate_test.go

@@ -25,18 +25,20 @@ func TestGate(t *testing.T) {
 	enabled := &atomic.Bool{}
 	enabled.Store(true)
 	g := &Gate{
-		id:             "test",
-		description:    "test gate",
-		enabled:        enabled,
-		stage:          StageAlpha,
-		referenceURL:   "http://example.com",
-		removalVersion: "v0.64.0",
+		id:           "test",
+		description:  "test gate",
+		enabled:      enabled,
+		stage:        StageAlpha,
+		referenceURL: "http://example.com",
+		fromVersion:  "v0.61.0",
+		toVersion:    "v0.64.0",
 	}
 
 	assert.Equal(t, "test", g.ID())
 	assert.Equal(t, "test gate", g.Description())
 	assert.True(t, g.IsEnabled())
 	assert.Equal(t, StageAlpha, g.Stage())
 	assert.Equal(t, "http://example.com", g.ReferenceURL())
-	assert.Equal(t, "v0.64.0", g.RemovalVersion())
+	assert.Equal(t, "v0.61.0", g.FromVersion())
+	assert.Equal(t, "v0.64.0", 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,