promote experimental code to stable

ktesting is heavily used in Kubernetes already for testing. The test package is
also used. The textlogger is not used that much yet because it was still
experimental (and thus no replacement for normal klog), but it's simple and
unlikely to need any breaking API changes.

Author: pohly

ktesting/init/init.go

@@ -17,11 +17,6 @@ limitations under the License.
 // Package init registers the command line flags for k8s.io/klogr/testing in
 // the flag.CommandLine. This is done during initialization, so merely
 // importing it is enough.
-//
-// # Experimental
-//
-// Notice: This package is EXPERIMENTAL and may be changed or removed in a
-// later release.
 package init
 
 import (

ktesting/options.go

@@ -29,11 +29,6 @@ import (
 // bind command line flags to the instance before passing it to NewTestContext.
 //
 // Must be constructed with NewConfig.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type Config struct {
 	vstate *verbosity.VState
 	co     configOptions
@@ -54,11 +49,6 @@ func (c *Config) VModule() flag.Value {
 }
 
 // ConfigOption implements functional parameters for NewConfig.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type ConfigOption func(co *configOptions)
 
 type configOptions struct {
@@ -72,23 +62,13 @@ type configOptions struct {
 // AnyToString overrides the default formatter for values that are not
 // supported directly by klog. The default is `fmt.Sprintf("%+v")`.
 // The formatter must not panic.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func AnyToString(anyToString func(value interface{}) string) ConfigOption {
 	return func(co *configOptions) {
 		co.anyToString = anyToString
 	}
 }
 
 // VerbosityFlagName overrides the default -testing.v for the verbosity level.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func VerbosityFlagName(name string) ConfigOption {
 	return func(co *configOptions) {
 		co.verbosityFlagName = name
@@ -97,11 +77,6 @@ func VerbosityFlagName(name string) ConfigOption {
 
 // VModulFlagName overrides the default -testing.vmodule for the per-module
 // verbosity levels.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func VModuleFlagName(name string) ConfigOption {
 	return func(co *configOptions) {
 		co.vmoduleFlagName = name
@@ -114,11 +89,6 @@ func VModuleFlagName(name string) ConfigOption {
 // https://github.com/kubernetes/community/blob/9406b4352fe2d5810cb21cc3cb059ce5886de157/contributors/devel/sig-instrumentation/logging.md#logging-conventions),
 // which is useful when debugging a failed test. `go test` only shows the log
 // output for failed tests. To see all output, use `go test -v`.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func Verbosity(level int) ConfigOption {
 	return func(co *configOptions) {
 		co.verbosityDefault = level
@@ -129,11 +99,6 @@ func Verbosity(level int) ConfigOption {
 // to being printed. Off by default. Unit tests that want to verify that
 // log entries are emitted as expected can turn this on and then retrieve
 // the captured log through the Underlier LogSink interface.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func BufferLogs(enabled bool) ConfigOption {
 	return func(co *configOptions) {
 		co.bufferLogs = enabled
@@ -142,11 +107,6 @@ func BufferLogs(enabled bool) ConfigOption {
 
 // NewConfig returns a configuration with recommended defaults and optional
 // modifications. Command line flags are not bound to any FlagSet yet.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func NewConfig(opts ...ConfigOption) *Config {
 	c := &Config{
 		co: configOptions{
@@ -165,11 +125,6 @@ func NewConfig(opts ...ConfigOption) *Config {
 }
 
 // AddFlags registers the command line flags that control the configuration.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func (c *Config) AddFlags(fs *flag.FlagSet) {
 	fs.Var(c.vstate.V(), c.co.verbosityFlagName, "number for the log level verbosity of the testing logger")
 	fs.Var(c.vstate.VModule(), c.co.vmoduleFlagName, "comma-separated list of pattern=N log level settings for files matching the patterns")

ktesting/setup.go

@@ -24,22 +24,12 @@ import (
 
 // DefaultConfig is the global default logging configuration for a unit
 // test. It is used by NewTestContext and k8s.io/klogr/testing/init.
-//
-// # Experimental
-//
-// Notice: This variable is EXPERIMENTAL and may be changed or removed in a
-// later release.
 var DefaultConfig = NewConfig()
 
 // NewTestContext returns a logger and context for use in a unit test case or
 // benchmark. The tl parameter can be a testing.T or testing.B pointer that
 // will receive all log output. Importing k8s.io/klogr/testing/init will add
 // command line flags that modify the configuration of that log output.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func NewTestContext(tl TL) (logr.Logger, context.Context) {
 	logger := NewLogger(tl, DefaultConfig)
 	ctx := logr.NewContext(context.Background(), logger)

ktesting/testinglogger.go

@@ -34,11 +34,6 @@ limitations under the License.
 //
 // Serialization of the structured log parameters is done in the same way
 // as for klog.InfoS.
-//
-// # Experimental
-//
-// Notice: This package is EXPERIMENTAL and may be changed or removed in a
-// later release.
 package ktesting
 
 import (
@@ -58,23 +53,13 @@ import (
 )
 
 // TL is the relevant subset of testing.TB.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type TL interface {
 	Helper()
 	Log(args ...interface{})
 }
 
 // NopTL implements TL with empty stubs. It can be used when only capturing
 // output in memory is relevant.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type NopTL struct{}
 
 func (n NopTL) Helper()                 {}
@@ -83,11 +68,6 @@ func (n NopTL) Log(args ...interface{}) {}
 var _ TL = NopTL{}
 
 // BufferTL implements TL with an in-memory buffer.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type BufferTL struct {
 	strings.Builder
 }
@@ -109,11 +89,6 @@ var _ TL = &BufferTL{}
 //
 // Verbosity can be modified at any time through the Config.V and
 // Config.VModule API.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func NewLogger(t TL, c *Config) logr.Logger {
 	l := tlogger{
 		shared: &tloggerShared{
@@ -141,11 +116,6 @@ func NewLogger(t TL, c *Config) logr.Logger {
 
 // Buffer stores log entries as formatted text and structured data.
 // It is safe to use this concurrently.
-//
-// # Experimental
-//
-// Notice: This interface is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type Buffer interface {
 	// String returns the log entries in a format that is similar to the
 	// klog text output.
@@ -156,32 +126,17 @@ type Buffer interface {
 }
 
 // Log contains log entries in the order in which they were generated.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type Log []LogEntry
 
 // DeepCopy returns a copy of the log. The error instance and key/value
 // pairs remain shared.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func (l Log) DeepCopy() Log {
 	log := make(Log, 0, len(l))
 	log = append(log, l...)
 	return log
 }
 
 // LogEntry represents all information captured for a log entry.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type LogEntry struct {
 	// Timestamp stores the time when the log entry was created.
 	Timestamp time.Time
@@ -214,38 +169,18 @@ type LogEntry struct {
 
 // LogType determines whether a log entry was created with an Error or Info
 // call.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type LogType string
 
 const (
 	// LogError is the special value used for Error log entries.
-	//
-	// Experimental
-	//
-	// Notice: This value is EXPERIMENTAL and may be changed or removed in
-	// a later release.
 	LogError = LogType("ERROR")
 
 	// LogInfo is the special value used for Info log entries.
-	//
-	// Experimental
-	//
-	// Notice: This value is EXPERIMENTAL and may be changed or removed in
-	// a later release.
 	LogInfo = LogType("INFO")
 )
 
 // Underlier is implemented by the LogSink of this logger. It provides access
 // to additional APIs that are normally hidden behind the Logger API.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type Underlier interface {
 	// GetUnderlying returns the testing instance that logging goes to.
 	// It returns nil when the test has completed already.

test/output.go

@@ -15,11 +15,6 @@ limitations under the License.
 */
 
 // Package test contains a reusable unit test for logging output and behavior.
-//
-// # Experimental
-//
-// Notice: This package is EXPERIMENTAL and may be changed or removed in a
-// later release.
 package test
 
 import (
@@ -48,11 +43,6 @@ import (
 //
 // The returned flag set has the klog flags registered. It can
 // be used to make further changes to the klog configuration.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func InitKlog(tb testing.TB) *flag.FlagSet {
 	state := klog.CaptureState()
 	tb.Cleanup(state.Restore)
@@ -77,11 +67,6 @@ func InitKlog(tb testing.TB) *flag.FlagSet {
 }
 
 // OutputConfig contains optional settings for Output.
-//
-// # Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type OutputConfig struct {
 	// NewLogger is called to create a new logger. If nil, output via klog
 	// is tested. Support for -vmodule is optional.  ClearLogger is called
@@ -553,12 +538,6 @@ var _, _, printWithKlogLine, _ = runtime.Caller(0) // anchor for finding the lin
 //
 // Loggers will be tested with direct calls to Info or
 // as backend for klog.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release. The test cases and thus the expected output also may
-// change.
 func Output(t *testing.T, config OutputConfig) {
 	for n, test := range tests {
 		t.Run(n, func(t *testing.T) {
@@ -879,12 +858,6 @@ func Output(t *testing.T, config OutputConfig) {
 //
 // Loggers will be tested with direct calls to Info or
 // as backend for klog.
-//
-// # Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release. The test cases and thus the expected output also may
-// change.
 func Benchmark(b *testing.B, config OutputConfig) {
 	for n, test := range tests {
 		b.Run(n, func(b *testing.B) {

test/zapr.go

@@ -18,11 +18,6 @@ package test
 
 // ZaprOutputMappingDirect provides a mapping from klog output to the
 // corresponding zapr output when zapr is called directly.
-//
-// # Experimental
-//
-// Notice: This package is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func ZaprOutputMappingDirect() map[string]string {
 	return map[string]string{
 		`I output.go:<LINE>] "test" akey="<&>"
@@ -282,11 +277,6 @@ I output.go:<LINE>] "odd WithValues" keyWithoutValue="(MISSING)"
 //   - zap drops keys with missing values, here we get "(MISSING)".
 //   - zap does not de-duplicate key/value pairs, here klog does that
 //     for it.
-//
-// # Experimental
-//
-// Notice: This package is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func ZaprOutputMappingIndirect() map[string]string {
 	mapping := ZaprOutputMappingDirect()