DOCSP-45211 Upgrade major versions

source/index.txt

@@ -24,6 +24,7 @@
    View the Source <https://github.com/mongodb/mongo-ruby-driver>
    API Documentation <{+api-root+}>
    What's New </whats-new>
+   Upgrade </upgrade>
    Compatibility </compatibility>
    Databases & Collections </databases-collection>
 
@@ -32,7 +33,6 @@
  Monitor Your Application </monitoring>
  Security </security>
  Issues & Help </issues-and-help>
- Upgrade </upgrade>
 
 Introduction
 ------------
@@ -104,11 +104,11 @@ What's New
 For a list of new features and changes in each version, see the :ref:`What's New <ruby-whats-new>`
 section.
 
-.. Upgrade Driver Versions
-.. -----------------------
+Upgrade Driver Versions
+-----------------------
 
-.. Learn what changes you must make to your application to upgrade driver
-.. versions in the :ref:`ruby-upgrade` section.
+Learn what changes you must make to your application to upgrade driver
+versions in the :ref:`ruby-upgrade` section.
 
 Compatibility
 -------------

source/upgrade.txt

@@ -0,0 +1,81 @@
+.. _ruby-upgrade:
+
+=======================
+Upgrade Driver Versions
+=======================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: backwards compatibility, update
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this section, you can identify the changes you must make to your application
+to upgrade your driver to a new version.
+
+Before you upgrade, perform the following actions:
+
+- Ensure the new driver version is compatible with the {+mdb-server+} versions
+  your application connects to and the Ruby versions your application runs on.
+  To view compatibility information, see the :ref:`Compatibility <ruby-compatibility>` page.
+
+- 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 <ruby-breaking-changes>` section.
+
+Starting with version 2.18.0, the driver uses feature flags to manage breaking
+changes. This feature allows you to opt into breaking changes before the next
+major version release.
+
+Versioning
+----------
+
+Each {+driver-short+} release has a version number in the format
+``MAJOR.MINOR.PATCH``. The {+driver-short+} uses `Semantic Versioning (SemVer)
+<https://semver.org/>`_, which typically means:
+
+- Breaking changes, enablement of new functionality, and removal of deprecated
+  functionality will only be done in major version releases.
+
+- New functionality will be added using feature flags, which must be enabled via
+  an opt-in configuration change. These feature flags may be added in either
+  major or minor releases.
+
+- Functionality may be marked as deprecated in either major or minor releases,
+  but will not be removed until the next major release, at the earliest.
+
+- Patch version releases will contain only non-breaking fixes and security
+  updates.
+
+.. _ruby-breaking-changes:
+
+Breaking Changes
+----------------
+
+A breaking change is a modification in a convention or behavior in
+a specific version of the driver that might prevent your application from
+working properly if not addressed before upgrading.
+
+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.
+
+.. _ruby-breaking-changes-2.20:
+
+Version 2.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking change:
+
+- Discontinues support for Ruby 2.5 and 2.6. Deprecates support for Ruby 2.7 and
+  JRuby 9.2.