promote non-test APIs to stable

As pointed out in
kubernetes/kubernetes#108725 (comment),
klog cannot carry "experimental" APIs that may end up in code that Kubernetes
depends on, whether it is directly or indirectly.

If that happens, Kubernetes might get stuck on a certain klog release because
one dependency depends on one klog release and another dependency on a
different, incompatible one.

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{})
 }