MONGOID-5510: Upgrading Guide (#5490)

* WIP on Upgrading Guide

* Update upgrading.txt

---------

Co-authored-by: shields <[email protected]>
Co-authored-by: Alex Bevilacqua <[email protected]>

Author: johnnyshields

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

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) <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.
+
+.. 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" <https://guides.rubyonrails.org/upgrading_ruby_on_rails.html>`_
+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 <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 <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.