Move TLS notes to compatibility page (#2225)

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: p-mongo

source/includes/ruby-driver-compatibility-full-language.rst

@@ -4,22 +4,47 @@ Installation
 
 .. default-domain:: mongodb
 
-The Ruby driver is bundled as a gem and is hosted on `Rubygems
+The Ruby driver is released as a gem hosted on `Rubygems
 <https://rubygems.org/gems/mongo>`_.
 
 
+Prerequisites
+=============
+
+Please see the :ref:`compatibility <compatibility>` page for the list of
+Ruby versions and MongoDB server versions that this release of the Ruby
+driver is compatible with.
+
+The driver itself is written entirely in Ruby, however it depends on the
+`bson library <https://rubygems.org/gems/bson>`_ which includes a C extension
+for MRI and a compiled Java extension for JRuby. A working C compiler and Ruby
+development headers and libraries are required when installing on MRI.
+When installing on JRuby, JRE is sufficient because the ``bson`` gem includes
+the compiled extension.
+
+Connecting to TLS-enabled MongoDB servers, using SCRAM authentication
+(both SCRAM-SHA-1 and SCRAM-SHA-256) and using X.509 authentication (which
+is performed over a TLS connection) requires the Ruby ``openssl`` extension
+to be present and working. The :ref:`TLS compatibility <tls-compatibility>`
+section provides further details on usage of newer TLS protocols like TLS 1.1.
+
+
 .. _ruby-driver-install:
 
 Install the Gem
 ===============
 
-The driver can be installed manually or with bundler.
+Add ``mongo`` to your ``Gemfile``:
+
+.. code-block:: ruby
 
-To install the mongo gem manually:
+  gem "mongo", "~> 2"
+
+To install the driver manually:
 
 .. code-block:: sh
 
-  gem install mongo -v 2.15.0.alpha
+  gem install mongo -v '~> 2'
 
 
 What's New
@@ -28,43 +53,3 @@ What's New
 Please consult the `releases page on GitHub
 <https://github.com/mongodb/mongo-ruby-driver/releases>`_ for the list
 of improvements and changes in each version of the driver.
-
-
-TLS/SSL and the Ruby Driver
-===========================
-
-Industry best practices, and some regulations, require the use of TLS 1.1
-or newer. Though no application changes are required for the Ruby driver to
-make use of the newest protocols, some operating systems or versions may
-not provide an OpenSSL version new enough to support them.
-
-Users of macOS older than 10.13 (High Sierra) will need to install Ruby from
-`rvm`_, `homebrew`_, `macports`_, or another similar source. See
-`installation information on ruby-lang.org`_ for more options.
-
-Users of Linux or other non-macOS Unix can check their OpenSSL version like this:
-
-.. 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 Ruby interpreter by executing 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']"
-
-You should see "TLS 1.X" where X is >= 1.
-
-You can read more about TLS versions and their security implications here:
-
-`<https://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols>`_
-
-.. _rvm: https://rvm.io/
-.. _homebrew: https://brew.sh/
-.. _macports: https://www.macports.org/
-.. _installation information on ruby-lang.org: https://www.ruby-lang.org/en/documentation/installation

source/includes/ruby-driver-compatibility-full-mongodb.rst

@@ -1,4 +1,4 @@
-.. _reference-compatibility-ruby:
+.. _compatibility:
 
 ********************
 Driver Compatibility
@@ -12,12 +12,23 @@ Driver Compatibility
    :depth: 1
    :class: singlecol
 
-.. _reference-compatibility-mongodb-ruby:
+
+.. _mongodb-compatibility:
 
 MongoDB Compatibility
 =====================
 
-.. include:: /includes/ruby-driver-compatibility-matrix-mongodb.rst
+The following compatibility table specifies the recommended
+version(s) of the MongoDB Ruby driver 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, meaning a
+particular version of the driver will generally work with newer versions of
+the server but may not take advantage of the functionality released in the
+newer version of the server.
+
+The first column lists the driver versions.
 
 .. list-table::
    :header-rows: 1
@@ -184,7 +195,8 @@ MongoDB Compatibility
 
 The driver does not support older versions of MongoDB.
 
-.. _reference-compatibility-language-ruby:
+
+.. _ruby-compatibility:
 
 Ruby Compatibility
 ==================
@@ -426,6 +438,7 @@ for that Ruby version is deprecated.
 
 The driver does not support older versions of Ruby.
 
+
 Rails/ActiveSupport Compatibility
 =================================
 
@@ -442,6 +455,52 @@ compatibility code for behavior like time serialization to be correct:
 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 will utilize the protocols supported by the underlying Ruby
+``openssl`` extension. In turn, the ``openssl`` extension generally exposes
+the functionality that exists 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 may not provide an OpenSSL version
+new enough to support these TLS versions.
+
+Users of macOS older than 10.13 (High Sierra) will need to install Ruby from
+`rvm`_, `homebrew`_, `macports`_, or another similar source. See
+`installation information on ruby-lang.org`_ for more options.
+
+Users of Linux or other non-macOS Unix can check their 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 Ruby interpreter by executing 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']"
+
+You should see "TLS 1.X" where X is >= 1.
+
+You can read more about TLS versions and their security implications `here
+<https://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet#Rule_-_Only_Support_Strong_Protocols>`_.
+
+.. _rvm: https://rvm.io/
+.. _homebrew: https://brew.sh/
+.. _macports: https://www.macports.org/
+.. _installation information on ruby-lang.org: https://www.ruby-lang.org/en/documentation/installation
+
+
 Atlas Compatibility
 ===================
 
@@ -454,6 +513,7 @@ When running on JRuby and connecting to Atlas Free Tier,
 `driver version 2.6.4 <https://github.com/mongodb/mongo-ruby-driver/releases/tag/v2.6.4>`_
 or higher and Java 8 or higher are required.
 
+
 ``mongo_kerberos`` Compatibility
 ================================