Upgrading Mongoid [upgrading]

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:

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.
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.
Review the Release Notes <release-notes> carefully when upgrading.
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.
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 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.