DOCSP-45212 Compatibility

source/compatibility.txt

@@ -0,0 +1,123 @@
+.. _ruby-compatibility:
+
+=============
+Compatibility
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: backwards compatibility, versions, upgrade 
+
+MongoDB Compatibility
+---------------------
+
+The following compatibility table specifies the recommended
+version(s) of the {+driver-long+} for use with a specific version of
+MongoDB. Except when indicated, the specified driver versions expose or
+take advantage of the features added in the corresponding server versions.
+
+MongoDB server releases are generally backwards compatible. This means a
+particular driver version will generally work with newer server versions but might
+not utilize the new functionalities in those server versions.
+
+The first column lists the driver versions.
+
+.. sharedinclude:: dbx/lifecycle-schedule-callout.rst
+
+.. include:: /includes/compatibility-table-legend-ruby.rst
+
+.. include:: /includes/mongodb-compatibility-table-ruby.rst
+
+The driver does not support older versions of MongoDB.
+
+Language Compatibility
+----------------------
+
+The following compatibility table specifies the versions of Ruby supported
+by the various versions of the {+driver-long+}.
+
+The first column lists the driver versions.
+
+.. include:: /includes/compatibility-table-legend-ruby.rst
+
+.. include:: /includes/language-compatibility-table-ruby.rst
+
+The driver does not support older versions of Ruby.
+
+Rails/ActiveSupport Compatibility
+---------------------------------
+
+The {+driver-short+} does not depend on ActiveSupport. However, if your
+application uses ActiveSupport or Ruby on Rails, you must load the driver's
+ActiveSupport compatibility code for behavior such as time serialization to be
+correct:
+
+.. code-block:: ruby
+
+   require 'mongo'
+   require 'mongo/active_support'
+
+Applications using Mongoid 7.0.6 or newer do not need to explicitly load
+the driver's ActiveSupport code, since Mongoid automatically does so.
+
+.. _tls-compatibility:
+
+TLS/SSL Compatibility
+----------------------
+
+The {+driver-short+} uses the protocols supported by the underlying Ruby
+``openssl`` extension. The ``openssl`` extension generally exposes
+the functionality available in the operating system's OpenSSL library.
+
+Industry best practices, and some regulations, require the use of TLS 1.1
+or newer. Some operating systems or versions might not provide an OpenSSL version
+that supports these TLS versions.
+
+If you use macOS older than 10.13 (High Sierra), you need to install Ruby from
+`rvm`_, `homebrew`_, `macports`_, or another similar source. See
+`Installing Ruby`_ for more options.
+
+If you use Linux or other non-macOS Unix systems, you can check your OpenSSL version
+as follows:
+
+.. code-block:: sh
+
+   openssl version
+
+If the version number is less than 1.0.1, support for TLS 1.1 or newer is
+not available. Contact your operating system vendor for a solution or upgrade
+to a newer distribution.
+
+You can check your TLS version by running the following command:
+
+.. code-block:: sh
+
+   ruby -e "require 'net/http'; require 'json'; puts JSON.parse(Net::HTTP.get(URI('https://www.howsmyssl.com/a/check')))['tls_version']"
+
+After running the command, you must see ``TLS 1.X`` where ``X`` is greater than
+or equal to ``1``.
+
+To learn more about TLS versions and their security implications, see `Transport Layer Security Cheat Sheet
+<https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Security_Cheat_Sheet.html>`_.
+
+.. _rvm: https://rvm.io/
+.. _homebrew: https://brew.sh/
+.. _macports: https://www.macports.org/
+.. _Installing Ruby: https://www.ruby-lang.org/en/documentation/installation
+
+JRuby and TLS Connections
+-------------------------
+
+Due to JRuby limitations:
+
+- The driver does not support ECDSA server certificates.
+- The driver does not perform OCSP endpoint checking.

source/includes/compatibility-table-legend-ruby.rst

@@ -0,0 +1,17 @@
+Compatibility Table Legend
+++++++++++++++++++++++++++
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility
+
+   * - Icon
+     - Explanation
+
+   * - ✓
+     - All features are supported.
+   * - D
+     - Support for the Driver version is deprecated.  
+   * - No mark
+     - The Driver version is not tested with the MongoDB version.

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

@@ -0,0 +1,138 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :class: compatibility-large no-padding
+
+   * - Ruby Driver
+     - Ruby 3.2
+     - Ruby 3.1
+     - Ruby 3.0
+     - Ruby 2.7
+     - Ruby 2.6
+     - JRuby 9.4
+     - JRuby 9.3
+     - JRuby 9.2
+     - JRuby 9.1
+
+   * - 2.20 to 2.21
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     - D
+     -
+     - |checkmark|
+     - |checkmark|
+     - D
+     -
+
+   * - 2.19
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     - D
+     -
+     - |checkmark|
+     - |checkmark|
+     -
+
+   * - 2.18
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     -
+     - |checkmark|
+     - |checkmark|
+     -
+
+   * - 2.17
+     -
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     -
+
+   * - 2.16
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     -
+
+   * - 2.15
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     -
+
+   * - 2.14
+     -
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     -
+
+   * - 2.11 to 2.13
+     -
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     -
+
+   * - 2.10
+     -
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+
+   * - 2.9
+     -
+     -
+     -
+     -
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+
+   * - 2.6 to 2.8
+     -
+     -
+     -
+     -
+     - |checkmark|
+     -
+     -
+     - |checkmark|
+     - |checkmark|
+
+.. include:: /includes/unicode-checkmark.rst