GODRIVER-3180 Document clearly that x/ package APIs are not stable. (#1631)

Author: matthewdale

x/README.md

@@ -1,6 +1,9 @@
-# MongoDB Go Driver Unstable Libraries
+# MongoDB Go Driver Experimental Packages
 
-This directory contains unstable MongoDB Go driver libraries and packages. The APIs of these
-packages are not stable and there is no backward compatibility guarantee.
+**WARNING: THESE PACKAGES ARE EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED
+WITHOUT NOTICE.**
 
-**THESE PACKAGES ARE EXPERIMENTAL AND SUBJECT TO CHANGE.**
+This directory contains packages intended only for internal use. They are made
+available to facilitate use cases that require access to internal MongoDB driver
+functionality and state. The APIs of these packages are not stable and there is
+no backward compatibility guarantee. Use with extreme caution!

x/bsonx/bsoncore/doc.go

@@ -4,26 +4,31 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
-// Package bsoncore contains functions that can be used to encode and decode BSON
-// elements and values to or from a slice of bytes. These functions are aimed at
-// allowing low level manipulation of BSON and can be used to build a higher
-// level BSON library.
+// Package bsoncore is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+//
+// Package bsoncore contains functions that can be used to encode and decode
+// BSON elements and values to or from a slice of bytes. These functions are
+// aimed at allowing low level manipulation of BSON and can be used to build a
+// higher level BSON library.
 //
 // The Read* functions within this package return the values of the element and
 // a boolean indicating if the values are valid. A boolean was used instead of
 // an error because any error that would be returned would be the same: not
 // enough bytes. This library attempts to do no validation, it will only return
 // false if there are not enough bytes for an item to be read. For example, the
 // ReadDocument function checks the length, if that length is larger than the
-// number of bytes available, it will return false, if there are enough bytes, it
-// will return those bytes and true. It is the consumers responsibility to
+// number of bytes available, it will return false, if there are enough bytes,
+// it will return those bytes and true. It is the consumers responsibility to
 // validate those bytes.
 //
 // The Append* functions within this package will append the type value to the
 // given dst slice. If the slice has enough capacity, it will not grow the
 // slice. The Append*Element functions within this package operate in the same
 // way, but additionally append the BSON type and the key before the value.
-//
-// Warning: Package bsoncore is unstable and there is no backward compatibility
-// guarantee. It is experimental and subject to change.
 package bsoncore

x/mongo/driver/DESIGN.md

@@ -0,0 +1,14 @@
+// Copyright (C) MongoDB, Inc. 2024-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package creds is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+package creds

x/mongo/driver/auth/creds/doc.go

@@ -4,20 +4,11 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
-// Package auth is not for public use.
+// Package auth is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
 //
-// The API for packages in the 'private' directory have no stability
-// guarantee.
-//
-// The packages within the 'private' directory would normally be put into an
-// 'internal' directory to prohibit their use outside the 'mongo' directory.
-// However, some MongoDB tools require very low-level access to the building
-// blocks of a driver, so we have placed them under 'private' to allow these
-// packages to be imported by projects that need them.
-//
-// These package APIs may be modified in backwards-incompatible ways at any
-// time.
-//
-// You are strongly discouraged from directly using any packages
-// under 'private'.
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package auth

x/mongo/driver/auth/doc.go

@@ -4,6 +4,13 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
+// Package connstring is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package connstring // import "go.mongodb.org/mongo-driver/x/mongo/driver/connstring"
 
 import (

x/mongo/driver/connstring/connstring.go

@@ -4,6 +4,13 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
+// Package dns is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package dns
 
 import (

x/mongo/driver/dns/dns.go

@@ -4,6 +4,13 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
+// Package driver is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package driver // import "go.mongodb.org/mongo-driver/x/mongo/driver"
 
 import (

x/mongo/driver/driver.go

@@ -0,0 +1,14 @@
+// Copyright (C) MongoDB, Inc. 2024-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package drivertest is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+package drivertest

x/mongo/driver/drivertest/doc.go

@@ -0,0 +1,14 @@
+// Copyright (C) MongoDB, Inc. 2024-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package integration is intended for internal use only. It is made available
+// to facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+package integration

x/mongo/driver/integration/doc.go

@@ -7,6 +7,13 @@
 //go:build !cse
 // +build !cse
 
+// Package mongocrypt is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package mongocrypt
 
 import (

x/mongo/driver/mongocrypt/mongocrypt_not_enabled.go

@@ -0,0 +1,14 @@
+// Copyright (C) MongoDB, Inc. 2024-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package options is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+package options

x/mongo/driver/mongocrypt/options/doc.go

@@ -4,6 +4,13 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
+// Package ocsp is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package ocsp
 
 import (

x/mongo/driver/ocsp/ocsp.go

@@ -0,0 +1,14 @@
+// Copyright (C) MongoDB, Inc. 2024-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package operation is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+package operation

x/mongo/driver/operation/doc.go

@@ -0,0 +1,14 @@
+// Copyright (C) MongoDB, Inc. 2024-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package session is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+package session

x/mongo/driver/session/doc.go

@@ -4,10 +4,19 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
-// Package topology contains types that handles the discovery, monitoring, and selection
-// of servers. This package is designed to expose enough inner workings of service discovery
-// and monitoring to allow low level applications to have fine grained control, while hiding
-// most of the detailed implementation of the algorithms.
+// Package topology is intended for internal use only. It is made available to
+// facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
+//
+// Package topology contains types that handles the discovery, monitoring, and
+// selection of servers. This package is designed to expose enough inner
+// workings of service discovery and monitoring to allow low level applications
+// to have fine grained control, while hiding most of the detailed
+// implementation of the algorithms.
 package topology // import "go.mongodb.org/mongo-driver/x/mongo/driver/topology"
 
 import (

x/mongo/driver/topology/topology.go

@@ -4,6 +4,13 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
+// Package wiremessage is intended for internal use only. It is made available
+// to facilitate use cases that require access to internal MongoDB driver
+// functionality and state. The API of this package is not stable and there is
+// no backward compatibility guarantee.
+//
+// WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT
+// NOTICE! USE WITH EXTREME CAUTION!
 package wiremessage
 
 import (