Skip to content

Add testable documentation examples to featuregate package #13159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add testable documentation examples to featuregate package #13159

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d87ca40
Add testable documentation examples to featuregate package
parv18050212 Jun 5, 2025
f2f5acf
Merge branch 'main' into add-featuregate-examples
parv18050212 Jun 5, 2025
c7869df
Improve featuregate package docs: focus on checking if a gate is enabled
parv18050212 Jun 5, 2025
b6453e7
Merge branch 'main' into add-featuregate-examples
parv18050212 Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions featuregate/doc.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

// Package featuregate provides mechanisms for feature flagging in the OpenTelemetry Collector.
//
// Example (Creating a feature gate and printing its properties):
//
// gate := featuregate.GlobalRegistry().MustRegister(
// "example.feature",
// featuregate.StageAlpha,
// featuregate.WithRegisterDescription("Example feature gate for demonstration."),
// featuregate.WithRegisterReferenceURL("https://example.com/feature"),
// featuregate.WithRegisterFromVersion("v0.1.0"),
// )
// fmt.Println("ID:", gate.ID())
// fmt.Println("Description:", gate.Description())
// fmt.Println("Stage:", gate.Stage())
// fmt.Println("ReferenceURL:", gate.ReferenceURL())
// fmt.Println("FromVersion:", gate.FromVersion())
// fmt.Println("IsEnabled:", gate.IsEnabled())
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than outputting every attribute here, I would show how to check the gate is enabled. That's the main thing someone looking to use this package will want to do.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the feedback!
I've updated the documentation to focus on the main use case: checking if a feature gate is enabled. The example now shows how to register a gate and use IsEnabled(), and the second example demonstrates registering, setting, and visiting gates in a concise way.

Let me know if you have any further suggestions or if there’s anything else I should adjust!

//
// Example (Registering, setting, and visiting feature gates):
//
// reg := featuregate.NewRegistry()
// gate := reg.MustRegister("example.feature2", featuregate.StageAlpha, featuregate.WithRegisterDescription("Another example."))
// _ = reg.Set(gate.ID(), true) // Enable the gate
// reg.VisitAll(func(g *featuregate.Gate) {
// fmt.Printf("Gate: %s, Enabled: %v, Description: %s\n", g.ID(), g.IsEnabled(), g.Description())
// })
//

Check failure on line 30 in featuregate/doc.go

View workflow job for this annotation

GitHub Actions / lint 

File is not properly formatted (gofumpt)
package featuregate
42 changes: 42 additions & 0 deletions featuregate/example_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
package featuregate_test

import (
"fmt"

Check failure on line 4 in featuregate/example_test.go

View workflow job for this annotation

GitHub Actions / lint 

File is not properly formatted (gofumpt)
"go.opentelemetry.io/collector/featuregate"
)

// Example_createFeatureGate demonstrates creating a feature gate and printing its properties.
func Example_createFeatureGate() {
gate := featuregate.GlobalRegistry().MustRegister(
"example.feature",
featuregate.StageAlpha,
featuregate.WithRegisterDescription("Example feature gate for demonstration."),
featuregate.WithRegisterReferenceURL("https://example.com/feature"),
featuregate.WithRegisterFromVersion("v0.1.0"),
)
fmt.Println("ID:", gate.ID())
fmt.Println("Description:", gate.Description())
fmt.Println("Stage:", gate.Stage())
fmt.Println("ReferenceURL:", gate.ReferenceURL())
fmt.Println("FromVersion:", gate.FromVersion())
fmt.Println("IsEnabled:", gate.IsEnabled())
// Output:
// ID: example.feature
// Description: Example feature gate for demonstration.
// Stage: Alpha
// ReferenceURL: https://example.com/feature
// FromVersion: v0.1.0
// IsEnabled: false
}

// Example_registrySetAndVisit demonstrates registering, setting, and visiting feature gates.
func Example_registrySetAndVisit() {
reg := featuregate.NewRegistry()
gate := reg.MustRegister("example.feature2", featuregate.StageAlpha, featuregate.WithRegisterDescription("Another example."))
_ = reg.Set(gate.ID(), true) // Enable the gate
reg.VisitAll(func(g *featuregate.Gate) {
fmt.Printf("Gate: %s, Enabled: %v, Description: %s\n", g.ID(), g.IsEnabled(), g.Description())
})
// Output:
// Gate: example.feature2, Enabled: true, Description: Another example.
}
Loading