From 59d071797639f35d4627eb7168350773495f8d0c Mon Sep 17 00:00:00 2001
From: Matt Dale <9760375+matthewdale@users.noreply.github.com>
Date: Thu, 27 Jun 2024 08:42:42 -0700
Subject: [PATCH] GODRIVER-3227 Deprecate bson.DefaultRegistry (#1688)

---
 bson/registry.go | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/bson/registry.go b/bson/registry.go
index b5b0f35687..d6afb2850e 100644
--- a/bson/registry.go
+++ b/bson/registry.go
@@ -10,15 +10,27 @@ import (
 	"go.mongodb.org/mongo-driver/bson/bsoncodec"
 )
 
-// DefaultRegistry is the default bsoncodec.Registry. It contains the default codecs and the
-// primitive codecs.
+// DefaultRegistry is the default bsoncodec.Registry. It contains the default
+// codecs and the primitive codecs.
+//
+// Deprecated: Use [NewRegistry] to construct a new default registry. To use a
+// custom registry when marshaling or unmarshaling, use the "SetRegistry" method
+// on an [Encoder] or [Decoder] instead:
+//
+//	dec, err := bson.NewDecoder(bsonrw.NewBSONDocumentReader(data))
+//	if err != nil {
+//	    panic(err)
+//	}
+//	dec.SetRegistry(reg)
+//
+// See [Encoder] and [Decoder] for more examples.
 var DefaultRegistry = NewRegistry()
 
 // NewRegistryBuilder creates a new RegistryBuilder configured with the default encoders and
 // decoders from the bsoncodec.DefaultValueEncoders and bsoncodec.DefaultValueDecoders types and the
 // PrimitiveCodecs type in this package.
 //
-// Deprecated: Use NewRegistry instead.
+// Deprecated: Use [NewRegistry] instead.
 func NewRegistryBuilder() *bsoncodec.RegistryBuilder {
 	rb := bsoncodec.NewRegistryBuilder()
 	bsoncodec.DefaultValueEncoders{}.RegisterDefaultEncoders(rb)