From 6baff1694fe79312b04555972dc0b0557c542fcf Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sun, 30 Jul 2023 22:23:38 +0200 Subject: [PATCH] log: add package documentation and summary of package's purpose Add a package doc to (try to) describe the purpose of this package, and to describe the purpose (and expectations) of aliases provided by the package. > Package log provides types and functions related to logging, passing > loggers through a context, and attaching context to the logger. > > # Transitional types > > This package contains various types that are aliases for types in [logrus]. > These aliases are intended for transitioning away from hard-coding logrus > as logging implementation. Consumers of this package are encouraged to use > the type-aliases from this package instead of directly using their logrus > equivalent. > > The intent is to replace these aliases with locally defined types and > interfaces once all consumers are no longer directly importing logrus > types. > > IMPORTANT: due to the transitional purpose of this package, it is not > guaranteed for the full logrus API to be provided in the future. As > outlined, these aliases are provided as a step to transition away from > a specific implementation which, as a result, exposes the full logrus API. > While no decisions have been made on the ultimate design and interface > provided by this package, we do not expect carrying "less common" features. Signed-off-by: Sebastiaan van Stijn --- log/context.go | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/log/context.go b/log/context.go index c3af05280..52687e28c 100644 --- a/log/context.go +++ b/log/context.go @@ -14,6 +14,27 @@ limitations under the License. */ +// Package log provides types and functions related to logging, passing +// loggers through a context, and attaching context to the logger. +// +// # Transitional types +// +// This package contains various types that are aliases for types in [logrus]. +// These aliases are intended for transitioning away from hard-coding logrus +// as logging implementation. Consumers of this package are encouraged to use +// the type-aliases from this package instead of directly using their logrus +// equivalent. +// +// The intent is to replace these aliases with locally defined types and +// interfaces once all consumers are no longer directly importing logrus +// types. +// +// IMPORTANT: due to the transitional purpose of this package, it is not +// guaranteed for the full logrus API to be provided in the future. As +// outlined, these aliases are provided as a step to transition away from +// a specific implementation which, as a result, exposes the full logrus API. +// While no decisions have been made on the ultimate design and interface +// provided by this package, we do not expect carrying "less common" features. package log import (