encoding: document when marshaling methods can be added

Fixes #10275

Change-Id: I2b3d54f3eb0f85d65324ddc3c3b2a797d42a16c9
Reviewed-on: https://go-review.googlesource.com/c/go/+/496537
Run-TryBot: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>

diff --git a/src/encoding/encoding.go b/src/encoding/encoding.go
index cc5a53699661d5fc31d2356a1dc33bf18acc0e58..50acf3c23a10138229288204e6a4c03e13907f86 100644 (file)
--- a/src/encoding/encoding.go
+++ b/src/encoding/encoding.go
@@ -9,6 +9,12 @@
 // interface once can make a type useful in multiple encodings.
 // Standard types that implement these interfaces include time.Time and net.IP.
 // The interfaces come in pairs that produce and consume encoded data.
+//
+// Adding encoding/decoding methods to existing types may constitute a breaking change,
+// as they can be used for serialization in communicating with programs
+// written with different library versions.
+// The policy for packages maintained by the Go project is to only allow
+// the addition of marshaling functions if no existing, reasonable marshaling exists.
 package encoding
 
 // BinaryMarshaler is the interface implemented by an object that can