[featuregates] Add fields for associated Issues and deprecated version

[MovieStoreGuy]

Description:
This PR extends the feature gate to add the fields IssueLinks and RemovalVersion to help provide context to users on:

• Why a feature gate exists?
• What is the associated issue(s)
• When will the feature gate will be removed

Link to tracking Issue:

#6167

Testing:

Tests have been updated to include updated to Gate life cycle as per the README

Documentation:

The featureflag README has been updated with an example.

[MovieStoreGuy]

@bogdandrutu ,

I know it has been some time since we spoken about this, but does to align on how envisioned how featuregates would work?

[codecov]

Codecov Report

Base: 91.89% // Head: 91.88% // Decreases project coverage by -0.01% ⚠️

Coverage data is based on head (02fb8c5) compared to base (9a56290).
Patch coverage: 95.47% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6447      +/-   ##
==========================================
- Coverage   91.89%   91.88%   -0.02%     
==========================================
  Files         237      237              
  Lines       13534    13687     +153     
==========================================
+ Hits        12437    12576     +139     
- Misses        869      882      +13     
- Partials      228      229       +1     

Impacted Files	Coverage Δ
service/internal/zpages/templates.go	41.66% <ø> (ø)
service/zpages.go	64.00% <0.00%> (-4.09%)	⬇️
obsreport/obsreport_exporter.go	97.90% <96.96%> (-2.10%)	⬇️
featuregate/gates.go	100.00% <100.00%> (ø)
internal/obsreportconfig/obsreportconfig.go	96.90% <100.00%> (ø)
obsreport/obsreporttest/obsreporttest.go	87.09% <100.00%> (-4.69%)	⬇️
obsreport/obsreporttest/otelprometheuschecker.go	93.40% <100.00%> (+1.73%)	⬆️
extension/zpagesextension/config.go	0.00% <0.00%> (-40.00%)	⬇️
extension/ballastextension/memory_ballast.go	82.14% <0.00%> (-7.15%)	⬇️
... and 1 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[MovieStoreGuy]

The patch is somewhat misleading here, it is not being directly tested, however, these new fields are being added to the templates which are being accessed.

[mx-psi]

I think adding an issue link is a non-controversial change, but the new stage is a bit confusing.

[bogdandrutu]

I like the change, but this makes me more nervous about the current API to register a gate. Feels a bit reversed that we construct a Gate pass a copy to the registry and then query the enable status by the registry.IsEnabled.

@MovieStoreGuy @mx-psi I don't know if you realized but the Enabled on the Gate does not return if the gate is enable or not in the current process (represents only the developer configuration). To get the runtime "configuration" need to call Registry.IsEnabled(id).

I find this more and more confusing, I wish we have something like:

type Registry struct {
}

func (r *Registry) MustRegister(id string, stage Stage, opts ..RegisterOptions) *Gate {
}

// Immutable object, owned by the `Registry`.
type Gate struct {
  ...
}

func (g *Gate) ID() string {
}

// Reflect the "runtime" status, so if somewhere else I have `reg.Apply(flags)` this will get changed since it is owned by the registry.
func (g *Gate) IsEnabled() bool {
}

[MovieStoreGuy]

That makes sense to me, it make the interaction with the registry clear and it's intent.

[bogdandrutu]

@MovieStoreGuy please add another chloggen entry for the deprecated fields. See https://github.com/open-telemetry/opentelemetry-collector/blob/main/.chloggen/providehelpers.yaml

[mx-psi]

LGTM, only a nit