promote contextual logging APIs to stable

README.md

@@ -28,12 +28,15 @@ Historical context is available here:
 Semantic versioning is used in this repository. It contains several Go modules
 with different levels of stability:
 - `k8s.io/klog/v2` - stable API, `vX.Y.Z` tags
-- `k8s.io/tools` - no stable API yet (may change eventually), `tools/v0.Y.Z` tags
+- `k8s.io/hack/tools` - no stable API yet (may change eventually or get moved to separate repo), `hack/tools/v0.Y.Z` tags
 - `examples` - no stable API, no tags, no intention to ever stabilize
 
 Exempt from the API stability guarantee are items (packages, functions, etc.)
 which are marked explicitly as `EXPERIMENTAL` in their docs comment. Those
-may still change in incompatible ways or get removed entirely.
+may still change in incompatible ways or get removed entirely. This can only
+be used for code that is used in tests to avoid situations where non-test
+code from two different Kubernetes dependencies depends on incompatible
+releases of klog because an experimental API was changed.
 
 ----
 

contextual.go

@@ -84,11 +84,6 @@ func SetLogger(logger logr.Logger) {
 // Supporting direct calls is recommended because it avoids the overhead of
 // routing log entries through klogr into klog and then into the actual Logger
 // backend.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func SetLoggerWithOptions(logger logr.Logger, opts ...LoggerOption) {
 	globalLogger = &logger
 	globalLoggerOptions = loggerOptions{}
@@ -100,23 +95,13 @@ func SetLoggerWithOptions(logger logr.Logger, opts ...LoggerOption) {
 // ContextualLogger determines whether the logger passed to
 // SetLoggerWithOptions may also get called directly. Such a logger cannot rely
 // on verbosity checking in klog.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func ContextualLogger(enabled bool) LoggerOption {
 	return func(o *loggerOptions) {
 		o.contextualLogger = enabled
 	}
 }
 
 // FlushLogger provides a callback for flushing data buffered by the logger.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func FlushLogger(flush func()) LoggerOption {
 	return func(o *loggerOptions) {
 		o.flush = flush
@@ -125,11 +110,6 @@ func FlushLogger(flush func()) LoggerOption {
 
 // LoggerOption implements the functional parameter paradigm for
 // SetLoggerWithOptions.
-//
-// Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type LoggerOption func(o *loggerOptions)
 
 type loggerOptions struct {
@@ -164,23 +144,13 @@ func ClearLogger() {
 // to avoid the additional overhead for contextual logging.
 //
 // This must be called during initialization before goroutines are started.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func EnableContextualLogging(enabled bool) {
 	contextualLoggingEnabled = enabled
 }
 
 // FromContext retrieves a logger set by the caller or, if not set,
 // falls back to the program's global logger (a Logger instance or klog
 // itself).
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func FromContext(ctx context.Context) Logger {
 	if contextualLoggingEnabled {
 		if logger, err := logr.FromContext(ctx); err == nil {
@@ -194,11 +164,6 @@ func FromContext(ctx context.Context) Logger {
 // TODO can be used as a last resort by code that has no means of
 // receiving a logger from its caller. FromContext or an explicit logger
 // parameter should be used instead.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func TODO() Logger {
 	return Background()
 }
@@ -207,11 +172,6 @@ func TODO() Logger {
 // that logger was initialized by the program and not by code that should
 // better receive a logger via its parameters. TODO can be used as a temporary
 // solution for such code.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func Background() Logger {
 	if globalLoggerOptions.contextualLogger {
 		// Is non-nil because globalLoggerOptions.contextualLogger is
@@ -224,11 +184,6 @@ func Background() Logger {
 
 // LoggerWithValues returns logger.WithValues(...kv) when
 // contextual logging is enabled, otherwise the logger.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func LoggerWithValues(logger Logger, kv ...interface{}) Logger {
 	if contextualLoggingEnabled {
 		return logger.WithValues(kv...)
@@ -238,11 +193,6 @@ func LoggerWithValues(logger Logger, kv ...interface{}) Logger {
 
 // LoggerWithName returns logger.WithName(name) when contextual logging is
 // enabled, otherwise the logger.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func LoggerWithName(logger Logger, name string) Logger {
 	if contextualLoggingEnabled {
 		return logger.WithName(name)
@@ -252,11 +202,6 @@ func LoggerWithName(logger Logger, name string) Logger {
 
 // NewContext returns logr.NewContext(ctx, logger) when
 // contextual logging is enabled, otherwise ctx.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func NewContext(ctx context.Context, logger Logger) context.Context {
 	if contextualLoggingEnabled {
 		return logr.NewContext(ctx, logger)

imports.go

@@ -24,35 +24,15 @@ import (
 // without directly importing it.
 
 // Logger in this package is exactly the same as logr.Logger.
-//
-// Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type Logger = logr.Logger
 
 // LogSink in this package is exactly the same as logr.LogSink.
-//
-// Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type LogSink = logr.LogSink
 
 // Runtimeinfo in this package is exactly the same as logr.RuntimeInfo.
-//
-// Experimental
-//
-// Notice: This type is EXPERIMENTAL and may be changed or removed in a
-// later release.
 type RuntimeInfo = logr.RuntimeInfo
 
 var (
 	// New is an alias for logr.New.
-	//
-	// Experimental
-	//
-	// Notice: This variable is EXPERIMENTAL and may be changed or removed in a
-	// later release.
 	New = logr.New
 )

klogr.go

@@ -25,11 +25,6 @@ import (
 // NewKlogr returns a logger that is functionally identical to
 // klogr.NewWithOptions(klogr.FormatKlog), i.e. it passes through to klog. The
 // difference is that it uses a simpler implementation.
-//
-// Experimental
-//
-// Notice: This function is EXPERIMENTAL and may be changed or removed in a
-// later release.
 func NewKlogr() Logger {
 	return New(&klogger{})
 }