From 59413575e4d0b1a3febbed6138ddaf5d82de7950 Mon Sep 17 00:00:00 2001
From: Tyler Yahn <MrAlias@users.noreply.github.com>
Date: Sun, 18 Feb 2024 08:01:24 -0800
Subject: [PATCH] Update otel/log package docs (#4935)

---
 log/doc.go | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 65 insertions(+), 3 deletions(-)

diff --git a/log/doc.go b/log/doc.go
index 8920510c0..c6f5ad4a7 100644
--- a/log/doc.go
+++ b/log/doc.go
@@ -14,8 +14,70 @@
 
 /*
 Package log provides the OpenTelemetry Logs Bridge API.
+
+This package is intended to be a bridge between existing logging libraries and
+OpenTelemetry. It is not designed to be a logging API itself.
+
+# API Implementations
+
+This package does not conform to the standard Go versioning policy, all of its
+interfaces may have methods added to them without a package major version bump.
+This non-standard API evolution could surprise an uninformed implementation
+author. They could unknowingly build their implementation in a way that would
+result in a runtime panic for their users that update to the new API.
+
+The API is designed to help inform an instrumentation author about this
+non-standard API evolution. It requires them to choose a default behavior for
+unimplemented interface methods. There are three behavior choices they can
+make:
+
+  - Compilation failure
+  - Panic
+  - Default to another implementation
+
+All interfaces in this API embed a corresponding interface from
+go.opentelemetry.io/otel/log/embedded. If an author wants the default behavior
+of their implementations to be a compilation failure, signaling to their users
+they need to update to the latest version of that implementation, they need to
+embed the corresponding interface from go.opentelemetry.io/otel/log/embedded in
+their implementation. For example,
+
+	import "go.opentelemetry.io/otel/log/embedded"
+
+	type LoggerProvider struct {
+		embedded.LoggerProvider
+		// ...
+	}
+
+If an author wants the default behavior of their implementations to a panic,
+they need to embed the API interface directly.
+
+	import "go.opentelemetry.io/otel/log"
+
+	type LoggerProvider struct {
+		log.LoggerProvider
+		// ...
+	}
+
+This is not a recommended behavior as it could lead to publishing packages that
+contain runtime panics when users update other package that use newer versions
+of go.opentelemetry.io/otel/log.
+
+Finally, an author can embed another implementation in theirs. The embedded
+implementation will be used for methods not defined by the author. For example,
+an author who wants to default to silently dropping the call can use
+o.opentelemetry.io/otel/log/noop:
+
+	import "go.opentelemetry.io/otel/log/noop"
+
+	type LoggerProvider struct {
+		noop.LoggerProvider
+		// ...
+	}
+
+It is strongly recommended that authors only embed
+go.opentelemetry.io/otel/log/noop if they choose this default behavior. That
+implementation is the only one OpenTelemetry authors can guarantee will fully
+implement all the API interfaces when a user updates their API.
 */
-
-// TODO (#4908): expand documentation stub.
-
 package log // import "go.opentelemetry.io/otel/log"