diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index c4460c31..12e7188b 100644 --- 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 ` 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 - ` 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 index 39fb839e..5f1d27e7 100644 --- 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 ` + page. + +- Address any breaking changes between the driver versions your application uses + and your planned upgrade version in the :ref:`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-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 ` 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 ` + 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``. \ No newline at end of file