From 60b76b3f96dba9aa7ffeb3b2580a996707e19e74 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 23 Jan 2025 10:39:29 -0800 Subject: [PATCH 1/3] add upgrade page and links --- source/index.txt | 10 +++--- source/upgrade.txt | 81 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 5 deletions(-) create mode 100644 source/upgrade.txt 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..90fe31a3 --- /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 MongoDB 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 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: + +- Drops support for Ruby 2.5 and 2.6. To upgrade to this version, ensure your + application runs on Ruby 2.7 or later. From 020a98b3659b2e7289a20c0802ae9d776fe1d916 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 23 Jan 2025 10:57:47 -0800 Subject: [PATCH 2/3] edits --- source/upgrade.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 90fe31a3..67f1bd0f 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -25,7 +25,7 @@ to upgrade your driver to a new version. Before you upgrade, perform the following actions: -- Ensure the new driver version is compatible with the MongoDB Server versions +- 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. @@ -77,5 +77,5 @@ Version 2.0 Breaking Changes This driver version introduces the following breaking change: -- Drops support for Ruby 2.5 and 2.6. To upgrade to this version, ensure your - application runs on Ruby 2.7 or later. +- Discontinues support for Ruby 2.5 and 2.6. Deprecates support for Ruby 2.7 and + JRuby 9.2. From 7dd500f7b5cca85050201f8d8886baca87fd230b Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 23 Jan 2025 12:21:37 -0800 Subject: [PATCH 3/3] mw feedback --- source/upgrade.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 67f1bd0f..1c20a0cf 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -64,7 +64,7 @@ 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. +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 @@ -72,8 +72,8 @@ changes between the current and upgrade versions. .. _ruby-breaking-changes-2.20: -Version 2.0 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Version 2.20 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This driver version introduces the following breaking change: