From a596006bafcca5b87e0ff3c75dbc1f686989ae45 Mon Sep 17 00:00:00 2001 From: Johnny Shields Date: Tue, 7 Feb 2023 02:46:40 +0900 Subject: [PATCH] MONGOID-5510: Upgrading Guide (#5490) * WIP on Upgrading Guide * Update upgrading.txt --------- Co-authored-by: shields Co-authored-by: Alex Bevilacqua --- docs/release-notes.txt | 1 + docs/release-notes/upgrading.txt | 119 +++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 docs/release-notes/upgrading.txt diff --git a/docs/release-notes.txt b/docs/release-notes.txt index 6d94a1a9a8..3f9f82b644 100644 --- a/docs/release-notes.txt +++ b/docs/release-notes.txt @@ -9,6 +9,7 @@ Release Notes .. toctree:: :titlesonly: + release-notes/upgrading release-notes/mongoid-9.0 release-notes/mongoid-8.1 release-notes/mongoid-8.0 diff --git a/docs/release-notes/upgrading.txt b/docs/release-notes/upgrading.txt new file mode 100644 index 0000000000..1ae90c1cfc --- /dev/null +++ b/docs/release-notes/upgrading.txt @@ -0,0 +1,119 @@ +.. _upgrading: + +***************** +Upgrading Mongoid +***************** + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + + +Mongoid provides a stable upgrade path for users migrate to new versions. + + +Versioning +========== + +Each Mongoid release has a version number in ``major.minor.patch`` format. Beginning in +Mongoid 7.4, Mongoid 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. + +.. warning:: + + Mongoid 7.3 and prior do not strictly adhere to SemVer and may contain breaking changes even + in minor version releases. Users should exercise additional caution when upgrading to + these versions. + + +How to Upgrade Mongoid +====================== + +Before you Upgrade +------------------ + +- *Test Coverage:* The best way to be sure that your application still works after upgrading +is to have good test coverage before you start the process. + +- *Upgrade Ruby and Rails:* See `"Upgrading Ruby on Rails" `_ +for more information + + +Upgrading Mongoid +----------------- + +The following outlines our recommended procedure to upgrade to a new Mongoid version: + +1. Upgrade to each minor version individually. + + For example, if you are upgrading from Mongoid 7.4 to 8.1, we recommend you follow this + procedure for the latest patch version of each minor version, e.g. first to 7.5.x, + then to 8.0.x, and finally to 8.1.x. + +2. Before upgrading, ensure you have ``load_defaults`` set to your current version. + + If you haven't yet enabled the latest behavior on your current version, you should do so + prior to upgrading. + +3. Review the :ref:`Release Notes ` carefully when upgrading. + +4. Test your app on the new version. + + Your app should be tested and released "as-is" on the new Mongoid version _without_ adjusting + ``load_defaults`` or any feature flags. + +5. Once Step 4 is confirmed to be stable, set ``load_defaults`` to the new version to enable + new functionality. Also fix any deprecation warnings at this time. + + You may also enable new functionalities one-by-one using feature flags. + + +Load Defaults and Feature Flags +------------------------------- + +When a feature flag is introduced, it will have a default value that preserves +the previous (legacy) functionality. At this time, users are encouraged to manually +set the flag to its new value in order to try out the new functionality. + +In the next major version release, the flag's default value will be flipped to +enable the new functionality. At this time, the flag itself will be marked deprecated. +Finally, the deprecated flag will be removed from the config entirely in a subsequent +major version release. + +Feature flags are added as a convenience to facilitate upgrading, but are not intended +to be supported in perpetuity. + + +Deprecation Policy +------------------ + +Mongoid may deprecate features, functionality, methods, constants, etc. from +time to time. To do so, Mongoid may take one or more of the following actions: + +- Mark the relevant code ``@deprecated`` in a code comment. + +- Add a log warning if the deprecated functionality is used. + +- Inform of the deprecation in the :ref:`Release Notes `. + +Mongoid may then remove the deprecated functionality in the next major version +release. + +Methods which are marked ``@api private`` may be removed without deprecation, +even if such methods are ``public`` in Ruby.