DOCSP-27661: Upgrade Driver page (mongodb#106)

* DOCSP-27661: Upgrade Driver page

* let me see

* first draft

* first draft v1.1

* second draft

* changes and new sections

* changes and new sections

* new and old fixes

* new and old fixes

* new and old fixes

* formatting

* final

Author: nickldp

source/index.txt

@@ -17,6 +17,7 @@ MongoDB C# Driver
    /connection-troubleshooting
    /issues-and-help
    /compatibility
+   /upgrade
    MongoDB Analyzer <https://www.mongodb.com/docs/mongodb-analyzer>
 
 Introduction
@@ -105,6 +106,13 @@ Compatibility
 For the compatibility charts that show the recommended {+driver-short+} version
 for each MongoDB Server version, see :ref:`csharp-compatibility-tables`.
 
+Upgrade Driver Versions
+-----------------------
+
+Learn what changes you may need to make to your application to upgrade
+driver versions in the :ref:`Upgrade Driver Versions <csharp-upgrade-driver>`
+section.
+
 MongoDB Analyzer
 ----------------
 

source/upgrade.txt

@@ -0,0 +1,123 @@
+.. _csharp-upgrade-driver:
+
+=======================
+Upgrade Driver Versions
+=======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+Overview
+--------
+
+In this section, you can identify essential changes you must make to your
+application when you upgrade your driver to a new version.
+
+Before you upgrade, perform the following actions:
+
+- Ensure the new version is compatible with the MongoDB Server versions
+  your application connects to and the {+framework+} version your
+  application runs on. See the :ref:`.NET/C# Driver Compatibility <csharp-compatibility-tables>`
+  page for this information.
+- Address any breaking changes between the current version of the driver
+  your application is using and your planned upgrade version in the
+  :ref:`Breaking Changes <csharp-breaking-changes>` section. To learn
+  more about the MongoDB Server release compatibility changes, see the
+  :ref:`<csharp-server-release-changes>` section.
+
+.. tip::
+
+   To minimize the number of changes your application may require when
+   upgrading driver versions in the future, use the
+   :ref:`{+stable-api+} <csharp-stable-api>`.
+
+.. _csharp-breaking-changes:
+
+Breaking Changes
+----------------
+
+A breaking change is a modification 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. For example, if you
+are upgrading the driver from v2.0 to v2.20, address all breaking changes from
+the version after v2.0 including any listed under v2.20.
+
+Version 2.19.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The ``ObjectSerializer`` only allows deserialization of
+  types that are considered safe. If not specified otherwise, the
+  ``ObjectSerializer`` uses the types returned by
+  ``ObjectSerializer.DefaultAllowedTypes``. 
+  
+  To learn more about the ``ObjectSerializer``, visit the
+  :ref:`FAQ <csharp-faq-object-serializer>`. For more information on
+  ``DefaultAllowedTypes``, visit the `API Documentation
+  <https://mongodb.github.io/mongo-csharp-driver/2.19/apidocs/html/P_MongoDB_Bson_Serialization_Serializers_ObjectSerializer_DefaultAllowedTypes.htm>`__.
+
+- The default ``LinqProvider`` has been changed to LINQ3. The ``LinqProvider``
+  can be configured for LINQ2 in ``MongoClientSettings`` as shown in the
+  following code example:
+  
+  .. code-block:: csharp
+    
+     var connectionString = "<connection string>";
+     var clientSettings = MongoClientSettings
+        .FromConnectionString(connectionString);
+     clientSettings.LinqProvider = LinqProvider.V2;
+     var client = new MongoClient(clientSettings);
+
+Version 2.14.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- This {+driver-long+} version removed support for {+framework+} v4.5.2 or earlier; the minimum
+  {+framework+} supported is v4.7.2.
+
+- This version of the {+driver-long+} does not support .NET Standard v1.5; the minimum .NET
+  Standard supported is v2.0.
+
+Version 2.13.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The ``slave0k`` connection string option was removed; the
+  ``readPreference`` option is now used instead.
+
+
+.. _csharp-server-release-changes:
+
+Server Release Compatibility Changes
+------------------------------------
+
+A server release compatibility change is a modification
+to the {+driver-long+} that discontinues support for a set of
+MongoDB Server versions.
+
+The driver discontinues support for a MongoDB Server version after it
+reaches end-of-life (EOL).
+
+To learn more about the MongoDB support for EOL products see the `Legacy
+Support Policy <https://www.mongodb.com/support-policy/legacy>`__. 
+
+To learn more about the compatibility between .NET/C# driver versions
+and MongoDB Server versions, visit the
+:ref:`Compatibility <csharp-compatibility-tables>` page. 
+
+Version 2.14 Release Support Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The v2.14 driver drops support for MongoDB Server v3.4 and earlier. To
+  use any driver from v2.14 and later, your MongoDB Server must be v3.6 or
+  later. To learn how to upgrade your MongoDB Server to v3.6, follow the
+  link that corresponds to your MongoDB deployment configuration:
+
+  - :ref:`<3.6-upgrade-replica-set>`
+  - :ref:`<3.6-upgrade-standalone>`
+  - :ref:`<3.6-upgrade-sharded-cluster>`

source/whats-new.txt

@@ -4,8 +4,6 @@
 What's New
 ==========
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none