diff --git a/source/index.txt b/source/index.txt index ae8d713d..4953b1a7 100644 --- a/source/index.txt +++ b/source/index.txt @@ -24,6 +24,7 @@ View the Source API Documentation <{+api-root+}> What's New + Upgrade Compatibility Databases & Collections @@ -32,7 +33,6 @@ Monitor Your Application Security Issues & Help - 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 ` 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 ------------- diff --git a/source/upgrade.txt b/source/upgrade.txt new file mode 100644 index 00000000..1c20a0cf --- /dev/null +++ b/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 ` 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 ` 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) +`_, 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 you don't address it 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.20 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.