mongodb · stephmarie17 · Jul 8, 2025 · Jul 7, 2025 · Jul 7, 2025 · Jul 7, 2025
diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt
@@ -49,13 +49,8 @@ What's New in 2.2
 
 .. important:: Breaking Change
 
-   The {+driver-short+} v2.2 release introduces the following breaking
-   change:
-
-   - Drops support for {+mdb-server+} v3.6. The minimum supported {+mdb-server+}
-     version is now v4.0. This also drops support for the ``MONGODB-CR`` authentication
-     mechanism. To learn more about compatibility with {+mdb-server+} 
-     versions, see the :ref:`Compatibility <golang-compatibility>` reference. 
+   The {+driver-short+} v2.2 release contains breaking changes. For more
+   information, see :ref:`version-2.2-breaking-changes`.
 
 This release includes the following improvements and fixes:
 
@@ -130,47 +125,8 @@ in the {+driver-short+} source code on GitHub.
 
 .. important:: Breaking Changes
 
-   The {+driver-short+} v2.0 release introduces the following breaking
-   changes:
-
-   - ``mongo.Connect()`` does not accept a Context parameter. This
-     method accepts only an options object. To view an example that uses
-     this method, see the :ref:`Connection Example Code
-     <go-connection-example-code>` in the Connection Guide.
-
-   - The ``Cursor.SetMaxTime()`` method is renamed to
-     ``Cursor.SetMaxAwaitTime()``. This method specifies the maximum time
-     that the server waits for new documents retrieved from a capped
-     collection with a tailable cursor.
-
-   - Removal of operation-specific timeout options. The following fields
-     and setter methods have been removed from the driver:
-
-     - ``AggregateOptions.MaxTime``, ``AggregateOptions.SetMaxTime()``
-     - ``ClientOptions.SocketTimeout``, ``ClientOptions.SetSocketTimeout()``
-     - ``CountOptions.MaxTime``, ``CountOptions.SetMaxTime()``
-     - ``DistinctOptions.MaxTime``, ``DistinctOptions.SetMaxTime()``
-     - ``EstimatedDocumentCountOptions.MaxTime``, ``EstimatedDocumentCountOptions.SetMaxTime()``
-     - ``FindOptions.MaxTime``, ``FindOptions.SetMaxTime()``
-     - ``FindOneOptions.MaxTime``, ``FindOneOptions.SetMaxTime()``
-     - ``FindOneAndReplaceOptions.MaxTime``, ``FindOneAndReplaceOptions.SetMaxTime()``
-     - ``FindOneAndUpdateOptions.MaxTime``, ``FindOneAndUpdateOptions.SetMaxTime()``
-     - ``GridFSFindOptions.MaxTime``, ``GridFSFindOptions.SetMaxTime()``
-     - ``CreateIndexesOptions.MaxTime``, ``CreateIndexesOptions.SetMaxTime()``
-     - ``DropIndexesOptions.MaxTime``, ``DropIndexesOptions.SetMaxTime()``
-     - ``ListIndexesOptions.MaxTime``, ``ListIndexesOptions.SetMaxTime()``
-     - ``SessionOptions.DefaultMaxCommitTime``, ``SessionOptions.SetDefaultMaxCommitTime()``
-     - ``TransactionOptions.MaxCommitTime``, ``TransactionOptions.SetMaxCommitTime()``
-     - ``WriteConcern.WTimeout``
-
-     Instead, you can set a timeout on your client or within a Context.
-     Learn more in the :ref:`golang-timeout-setting` section of the
-     Connection Options guide.
-
-   - Removal of the ``bson/primitive`` package. This package is now merged with
-     the ``bson`` package. To update your code, remove any ``bson/primitive``
-     import statements and change any instance of ``primitive.ObjectID`` to
-     ``bson.ObjectId``.
+   The {+driver-short+} v2.0 release contains breaking changes. For more
+   information, see :ref:`version-2.0-breaking-changes`.
 
 This release includes the following improvements and fixes:
 

diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt
@@ -1,2 +1,106 @@
-.. TODO
+.. _golang-upgrade:
 
+=======================
+Upgrade Driver Versions
+=======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: compatibility, backwards compatibility
+
+Overview
+--------
+
+This page describes the changes you must make to your application
+when you upgrade to a new version of the {+driver-short+}.
+
+Before you upgrade, perform the following actions:
+
+- Ensure the new {+driver-short+} version is compatible with the {+mdb-server+}
+  version your application connects to and the Go version your application runs
+  on. For more information, see the :ref:`Compatibility <golang-compatibility>`
+  page.
+
+- Address any breaking changes between the driver versions your application uses
+  and your planned upgrade version in the :ref:`Breaking Changes
+  <golang-breaking-changes>` section. 
+
+.. tip::
+
+   To minimize the number of changes your application requires when
+   upgrading driver versions in the future, use the :ref:`{+stable-api+} <golang-stable-api>`.
+
+.. _golang-breaking-changes:
+
+Breaking Changes
+----------------
+
+A breaking change is a change of a convention or a behavior starting in a specific
+version of the driver. This type of change may prevent your application from working
+properly if not addressed before upgrading the driver.
+
+The breaking changes in this section are categorized by the driver version that introduced
+them. When upgrading driver versions, address all the breaking changes between the current
+and upgrade versions.
+
+.. _version-2.2-breaking-changes:
+
+Version 2.2 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Drops support for {+mdb-server+} v3.6. The minimum supported {+mdb-server+}
+  version is now v4.0. This also drops support for the ``MONGODB-CR`` authentication
+  mechanism. To learn more about compatibility with {+mdb-server+} 
+  versions, see the :ref:`Compatibility <golang-compatibility>` reference. 
+
+.. _version-2.0-breaking-changes:
+
+Version 2.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``mongo.Connect()`` does not accept a Context parameter. This
+  method accepts only an options object. To view an example that uses this
+  method, see the :ref:`Connection Example Code <go-connection-example-code>`
+  in the Connection Guide.
+
+- The ``Cursor.SetMaxTime()`` method is renamed to
+  ``Cursor.SetMaxAwaitTime()``. This method specifies the maximum time
+  that the server waits for new documents retrieved from a capped
+  collection with a tailable cursor.
+
+- Removal of operation-specific timeout options. The following fields
+  and setter methods have been removed from the driver:
+
+  - ``AggregateOptions.MaxTime``, ``AggregateOptions.SetMaxTime()``
+  - ``ClientOptions.SocketTimeout``, ``ClientOptions.SetSocketTimeout()``
+  - ``CountOptions.MaxTime``, ``CountOptions.SetMaxTime()``
+  - ``DistinctOptions.MaxTime``, ``DistinctOptions.SetMaxTime()``
+  - ``EstimatedDocumentCountOptions.MaxTime``, ``EstimatedDocumentCountOptions.SetMaxTime()``
+  - ``FindOptions.MaxTime``, ``FindOptions.SetMaxTime()``
+  - ``FindOneOptions.MaxTime``, ``FindOneOptions.SetMaxTime()``
+  - ``FindOneAndReplaceOptions.MaxTime``, ``FindOneAndReplaceOptions.SetMaxTime()``
+  - ``FindOneAndUpdateOptions.MaxTime``, ``FindOneAndUpdateOptions.SetMaxTime()``
+  - ``GridFSFindOptions.MaxTime``, ``GridFSFindOptions.SetMaxTime()``
+  - ``CreateIndexesOptions.MaxTime``, ``CreateIndexesOptions.SetMaxTime()``
+  - ``DropIndexesOptions.MaxTime``, ``DropIndexesOptions.SetMaxTime()``
+  - ``ListIndexesOptions.MaxTime``, ``ListIndexesOptions.SetMaxTime()``
+  - ``SessionOptions.DefaultMaxCommitTime``, ``SessionOptions.SetDefaultMaxCommitTime()``
+  - ``TransactionOptions.MaxCommitTime``, ``TransactionOptions.SetMaxCommitTime()``
+  - ``WriteConcern.WTimeout``
+
+  Instead, you can set a timeout on your client or within a Context.
+  Learn more in the :ref:`golang-csot` guide.
+
+- Removal of the ``bson/primitive`` package. This package is now merged with
+  the ``bson`` package. To update your code, remove any ``bson/primitive``
+  import statements and change any instance of ``primitive.ObjectID`` to
+  ``bson.ObjectId``.