DOCSP-42772: compatibility

snooty.toml

@@ -3,9 +3,12 @@ title = "Mongoid"
 
 intersphinx = [
     "https://www.mongodb.com/docs/manual/objects.inv",
+    "https://www.mongodb.com/docs/drivers/objects.inv",
     "https://www.mongodb.com/docs/atlas/objects.inv",
 ]
 
+sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
+
 toc_landing_pages = [
     "/quick-start-rails",
     "/quick-start-sinatra",
@@ -23,6 +26,7 @@ version = "9.0"
 full-version = "{+version+}.4"
 ruby-driver = "Ruby driver"
 language = "Ruby"
+ror = "{+language+} on Rails"
 quickstart-sinatra-app-name = "my-sinatra-app"
 quickstart-rails-app-name = "my-rails-app"
 feedback-widget-title = "Feedback"

source/add-existing.txt

@@ -21,7 +21,7 @@ Overview
 --------
 
 In this guide, you can learn how to add {+odm+} to an existing Sinatra
-or Ruby on Rails (Rails) application. To learn how to set up a new
+or {+ror+} (Rails) application. To learn how to set up a new
 application that uses {+odm+}, see one of the following guides:
 
 - :ref:`mongoid-quick-start-rails`

source/additional-resources.txt

@@ -26,10 +26,10 @@ Screencasts
   of setting up an app, querying for documents, adding embedded
   associations, overriding the id, and more.
 
-- `Ruby on Rails Web Services and Integration with MongoDB, Week 3: Mongoid
+- `{+ror+} Web Services and Integration with MongoDB, Week 3: Mongoid
   <https://www.youtube.com/watch?v=9LylgiMYsUM>`_
 
-  A detailed introduction to Mongoid and Ruby on Rails web services.
+  A detailed introduction to Mongoid and {+ror+} web services.
 
 - `Create a search bar in Rails with Mongoid
   <https://www.youtube.com/watch?v=zusWR8jS5-A>`_
@@ -48,9 +48,9 @@ Articles
 
   Creating a Sinatra API with Mongoid.
 
-- `Converting an existing Ruby on Rails application to MongoDB <https://ibraheem.ca/posts/convert-rails-to-mongodb>`_
+- `Converting an existing {+ror+} application to MongoDB <https://ibraheem.ca/posts/convert-rails-to-mongodb>`_
 
-  How to Convert an existing Ruby on Rails application to use MongoDB and Mongoid.
+  How to Convert an existing {+ror+} application to use MongoDB and Mongoid.
 
 
 Sample Applications

source/compatibility.txt

@@ -0,0 +1,108 @@
+.. _mongoid-compatibility:
+
+=============
+Compatibility
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: backwards compatibility, versions, upgrade
+
+{+language+} Driver Compatibility
+-------------------------
+
+The following compatibility table specifies the versions of the
+:ruby:`{+ruby-driver+} </>` that are compatible with each
+{+odm+} version.
+
+.. note:: Patch Version Compatibility
+
+  Older patch versions of {+odm+} within the same minor release might
+  support older {+ruby-driver+} versions. For example, {+odm+} v7.0.5
+  supports {+ruby-driver+} v2.5 and later, but {+odm+} v7.0.6 requires
+  driver v2.7 or later.
+
+.. include:: /includes/ruby-driver-compatibility-table-mongoid.rst
+
+MongoDB Compatibility
+---------------------
+
+The following compatibility table specifies the recommended version or versions
+of {+odm+} that you can use with a specific version of MongoDB. To use
+features of a particular MongoDB Server version, both the
+{+ruby-driver+} and {+odm+} must be compatible with that MongoDB
+version. To learn about the driver's MongoDB compatibility details,
+see :ruby:`Compatibility </reference/driver-compatibility/>`
+in the {+ruby-driver+} documentation.
+
+The first column lists the version of {+odm+}.
+
+.. sharedinclude:: dbx/lifecycle-schedule-callout.rst
+
+.. sharedinclude:: dbx/compatibility-table-legend.rst
+
+.. include:: /includes/mongodb-compatibility-table-mongoid.rst
+
+To learn more about how to read the compatibility tables, see the guide
+on :ref:`MongoDB Compatibility Tables <about-driver-compatibility>`.
+
+Language Compatibility
+----------------------
+
+The following compatibility table specifies the recommended version or
+versions of {+odm+} that you can use with specific {+language+}
+interpreter versions.
+
+The first column lists the version of {+odm+}.
+
+.. include:: /includes/language-compatibility-table-mongoid.rst
+
+To learn more about how to read the compatibility tables, see the guide
+on :ref:`MongoDB Compatibility Tables <about-driver-compatibility>`.
+
+{+ror+} Compatibility
+---------------------------
+
+The following compatibility table specifies which versions of {+ror+}
+are supported by {+odm+}.
+
+.. include:: /includes/rails-compatibility-table-mongoid.rst
+
+Rails Frameworks Support
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+{+odm+} is compatible with many of the frameworks that comprise {+ror+}.
+In this section, you can learn about which frameworks you can use with {+odm+}.
+
+{+odm+} attempts to offer API compatibility with `Active Record
+<{+active-record-docs+}/active_record_basics.html>`__, but libraries
+that depend directly on Active Record might not work as expected if you
+use {+odm+} as a direct replacement.
+
+.. note::
+
+  You can use {+odm+} alongside Active Record within the same
+  application.
+
+.. include:: /includes/ror-compatibility-table-mongoid.rst
+
+How to Get Help
+---------------
+
+If you have questions about compatibility, visit the following resources
+for further guidance:
+
+- Ask questions on our :community-forum:`MongoDB Community Forums <>`.
+- Visit the :technical-support:`Support Channels </>`.
+- File an issue or feature request in Jira, our issue tracker. You can
+  find instructions on filing a ticket on the
+  :ref:`mongoid-issues-and-help` page.

source/ecosystem.txt

@@ -19,7 +19,7 @@ Projects
 
 - `Workarea Commerce <https://github.com/workarea-commerce/workarea>`_
 
-  Workarea is an enterprise-grade Ruby on Rails commerce platform that uses Mongoid.
+  Workarea is an enterprise-grade {+ror+} commerce platform that uses Mongoid.
 
 
 Extension Libraries

source/includes/language-compatibility-table-mongoid.rst

@@ -0,0 +1,48 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility-large
+
+   * - {+odm+} Version
+     - {+language+} 3.2
+     - {+language+} 3.1
+     - {+language+} 3.0
+     - {+language+} 2.7
+     - {+language+} 2.6
+     - {+language+} 2.5
+     - J{+language+} 9.4
+     - J{+language+} 9.3
+     - J{+language+} 9.2
+
+   * - 9.0
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     -
+     -
+     - ✓
+     -
+     -
+
+   * - 8.1
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     -
+     -
+     - ✓
+     -
+
+   * - 8.0
+     -
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     -
+     -
+     - ✓
+     -

source/includes/mongodb-compatibility-table-mongoid.rst

@@ -0,0 +1,34 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility-large
+
+   * - {+odm+} Version
+     - MongoDB 8.0
+     - MongoDB 7.0
+     - MongoDB 6.0
+     - MongoDB 5.0
+     - MongoDB 4.4
+     - MongoDB 4.2
+     - MongoDB 4.0
+     - MongoDB 3.6
+
+   * - 9.0
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+
+   * - 8.0 to 8.1
+     -
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓
+     - ✓

source/includes/rails-compatibility-table-mongoid.rst

@@ -0,0 +1,52 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility-large no-padding
+
+   * - {+odm+} Version
+     - Rails 8.0
+     - Rails 7.2
+     - Rails 7.1
+     - Rails 7.0
+     - Rails 6.1
+     - Rails 6.0
+     - Rails 5.2
+     - Rails 5.1
+
+   * - 9.0
+     - ✓ [#rails-8.0]_
+     - ✓ [#rails-7.2]_
+     - ✓ [#rails-7.1]_
+     - ✓
+     - ✓
+     - ✓
+     -
+     -
+
+   * - 8.1
+     - ✓ [#rails-8.0]_
+     - ✓ [#rails-7.2]_
+     - ✓ [#rails-7.1]_
+     - ✓
+     - ✓
+     - ✓
+     - ✓ [#rails-5-ruby-3.0]_
+     -
+
+   * - 8.0
+     -
+     -
+     - ✓ [#rails-7.1]_
+     - ✓
+     - ✓
+     - ✓
+     - ✓ [#rails-5-ruby-3.0]_
+     -
+
+.. [#rails-8.0] Rails 8.0 requires {+odm+} v8.1.7 and v9.0.3 in the respective 8.1 and 9.0 stable branches.
+
+.. [#rails-7.2] Rails 7.2 requires {+odm+} v8.1.6 and v9.0.2 in the respective 8.1 and 9.0 stable branches.
+
+.. [#rails-7.1] Rails 7.1 requires {+odm+} v8.0.7 or v8.1.3 in the respective 8.0 and 8.1 stable branches.
+
+.. [#rails-5-ruby-3.0] Using Rails 5.x with Ruby 3 is not supported.

source/includes/ror-compatibility-table-mongoid.rst

@@ -0,0 +1,65 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility-large
+
+   * - Rails Framework
+     - {+odm+} Support
+
+   * - ``ActionCable``
+     - | ✓
+       | There is no MongoDB adapter for ``ActionCable``, but you can
+         use any existing adapter, such as the `Redis Adapter
+         <{+active-record-docs+}/action_cable_overview.html#redis-adapter>`__,
+         alongside {+odm+} models.
+
+   * - ``ActionMailbox``
+     - | *Unsupported*
+       | Depends directly on Active Record.
+
+   * - ``ActionMailer``
+     - ✓
+
+   * - ``ActionPack``
+     - ✓
+
+   * - ``ActionText``
+     - | *Unsupported*
+       | Depends directly on Active Record.
+
+   * - ``ActionView``
+     - ✓
+
+   * - ``ActiveJob``
+     - | ✓
+       | Serialization of BSON and {+odm+} objects works best if you
+         explicitly send ``BSON::ObjectId`` values as strings, and
+         reconstitute them in the job, as shown in the following code:
+  
+       .. code-block:: ruby
+       
+          record = Model.find(...)
+          MyJob.perform_later(record._id.to_s)
+   
+          class MyJob < ApplicationJob
+            def perform(id_as_string)
+              record = Model.find(id_as_string)
+              # ...
+            end
+          end
+
+   * - ``ActiveModel``
+     - | ✓ 
+       | The ``Mongoid::Document`` module includes
+         ``ActiveModel::Model`` and leverages ``ActiveModel::Validations``
+         for :ref:`mongoid-modeling-validation`.
+
+   * - ``ActiveStorage``
+     - | *Unsupported*
+       | Depends directly on Active Record.
+
+   * - ``ActiveSupport``
+     - | ✓
+       | The ``Mongoid`` module requires ``ActiveSupport``.
+         ``Mongoid`` uses ``ActiveSupport::TimeWithZone`` for handling
+         time values.

source/includes/ruby-driver-compatibility-table-mongoid.rst

@@ -0,0 +1,14 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility-large
+
+   * - {+odm+} Version
+     - {+ruby-driver+} 2.18 to 2.21
+     - {+ruby-driver+} 2.10 to 2.17
+     - {+ruby-driver+} 2.7 to 2.9
+
+   * - 8.0 to 9.0
+     - ✓
+     -
+     -