DOCSP-34087-compatibility-updates (#352)

jason-price-mongodb · jason-price-mongodb · web-flow · commit 4f21a38689db · 2024-08-30T10:59:33.000-07:00
* DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates * DOCSP-34087-compatibility-updates --------- Co-authored-by: jason-price-mongodb <jshfjghsdfgjsdjh@aolsdjfhkjsdhfkjsdf.com>
diff --git a/source/includes/fact-mongoshrc-loading.rst b/source/includes/fact-mongoshrc-loading.rst
@@ -13,8 +13,4 @@ on the command line or by specifying a :ref:`.js file
 
 .. note:: Legacy Shell Configuration 
 
-   The legacy :binary:`~bin.mongo` shell used a configuration file called 
-   ``.mongorc.js``. If :binary:`mongosh` detects this file on startup and 
-   ``.mongoshrc.js`` is not present, :binary:`mongosh` does not load the legacy 
-   ``.mongorc.js`` file, and suggests renaming ``.mongorc.js`` to 
-   ``.mongoshrc.js``.
+   .. include:: /includes/legacy/legacy-shell-configuration.rst
diff --git a/source/includes/legacy/legacy-command-exceptions.rst b/source/includes/legacy/legacy-command-exceptions.rst
@@ -0,0 +1,3 @@
+For commands whose output includes ``{ ok: 0 }``, ``mongosh`` returns a
+consistent exception and omits the server raw output. The legacy
+``mongo`` shell returns output that varies for each command.
diff --git a/source/includes/legacy/legacy-data-types.rst b/source/includes/legacy/legacy-data-types.rst
@@ -0,0 +1,4 @@
+MongoDB stores data using :manual:`BSON </reference/bson-types>`, which
+supports additional data types that aren't available in :term:`JSON`.
+The ``mongosh`` shell has better data type support for
+:ecosystem:`drivers </drivers>` than the legacy ``mongo`` shell.
diff --git a/source/includes/legacy/legacy-load-method.rst b/source/includes/legacy/legacy-load-method.rst
@@ -0,0 +1,2 @@
+The legacy ``mongo`` shell cannot access a script's file name or
+directory in the ``load()`` method.
diff --git a/source/includes/legacy/legacy-output.rst b/source/includes/legacy/legacy-output.rst
@@ -0,0 +1,5 @@
+The ``mongosh`` shell returns output that differs from the legacy
+``mongo`` shell. If you have scripts that require the output to be
+formatted in a similar way to the legacy ``mongo`` shell, try
+reformatting the ``mongosh`` output with :ref:`EJSON.stringify()
+<mongosh-ejson-stringify>`.
diff --git a/source/includes/legacy/legacy-retryable-writes.rst b/source/includes/legacy/legacy-retryable-writes.rst
@@ -0,0 +1,7 @@
+By default, retryable writes are:
+
+- enabled in :binary:`mongosh`
+- disabled in the legacy ``mongo`` shell
+
+To disable retryable writes, use :option:`--retryWrites=false <mongosh
+--retryWrites>`.
diff --git a/source/includes/legacy/legacy-shell-configuration.rst b/source/includes/legacy/legacy-shell-configuration.rst
@@ -0,0 +1,6 @@
+The legacy ``mongo`` shell uses a configuration file named
+``.mongorc.js``.
+
+If :binary:`mongosh` finds ``.mongorc.js`` on startup but doesn't find
+``.mongoshrc.js``, ``mongosh`` doesn't load the legacy ``.mongorc.js``
+file and states you should rename ``.mongorc.js`` to ``.mongoshrc.js``.
diff --git a/source/reference/compatibility.txt b/source/reference/compatibility.txt
@@ -240,3 +240,51 @@ Limitations on Database Calls
 
 .. include:: /includes/fact-call-limitations.rst
 
+Command Exceptions
+------------------
+
+.. include:: /includes/legacy/legacy-command-exceptions.rst
+
+For details, see :ref:`run-commands`.
+
+Shell Configuration
+-------------------
+
+.. include:: /includes/legacy/legacy-shell-configuration.rst
+
+For details, see :ref:`mongoshrc-js`.
+
+Data Types
+----------
+
+.. include:: /includes/legacy/legacy-data-types.rst
+
+For details, see :ref:`mongo-shell-data-types`.
+
+Methods
+-------
+
+.. include:: /includes/legacy/legacy-load-method.rst
+
+For details, see :ref:`load() <mongosh-native-method-load>`.
+
+Retryable Writes
+----------------
+
+.. include:: /includes/legacy/legacy-retryable-writes.rst
+
+For details, see :option:`--retryWrites`.
+
+Legacy Output
+-------------
+
+.. include:: /includes/legacy/legacy-output.rst
+
+For details, see :ref:`mongosh-ejson-stringify-legacy-output`.
+
+Code Snippets
+-------------
+
+Working with code snippets is different for the legacy ``mongo`` shell.
+
+For details, see :ref:`snip-get-help`.
diff --git a/source/reference/data-types.txt b/source/reference/data-types.txt
@@ -1,3 +1,5 @@
+.. _mongo-shell-data-types:
+
 ==========
 Data Types
 ==========
@@ -12,12 +14,7 @@ Data Types
 
 .. _mongo-shell-data-type:
 
-MongoDB Server stores data using the
-:manual:`BSON </reference/bson-types>` format which supports some
-additional data types that are not available using the :term:`JSON`
-format. Compared to the legacy ``mongo`` shell, MongoDB Shell
-(``mongosh``) has type handling which is better aligned with the
-default types used by the MongoDB :ecosystem:`drivers </drivers>`. 
+.. include:: /includes/legacy/legacy-data-types.rst
 
 This document highlights changes in type usage between ``mongosh`` and
 the legacy ``mongo`` shell. See the 
diff --git a/source/reference/ejson/stringify.txt b/source/reference/ejson/stringify.txt
@@ -613,12 +613,12 @@ The output is:
      }
    ]
 
+.. _mongosh-ejson-stringify-legacy-output:
+
 Legacy ``tojsononeline()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``mongosh`` formats query output differently than the deprecated
-``mongo`` shell. You may have scripts which rely on the old format. To
-reformat ``mongosh`` output on a single line, use ``EJSON.stringify()``.
+.. include:: /includes/legacy/legacy-output.rst
 
 Run a sample query in ``mongosh`` and ``mongo`` to see the different
 formats.
diff --git a/source/reference/methods.txt b/source/reference/methods.txt
@@ -883,8 +883,7 @@ Native Methods
        script, respectively. The returned values are always absolute
        paths.
 
-       In the legacy shell, you cannot not access the script's file name
-       or directory using the ``load()`` method.
+       .. include:: /includes/legacy/legacy-load-method.rst
 
    * - .. _mongosh-native-method-print:  
 
diff --git a/source/reference/options.txt b/source/reference/options.txt
@@ -562,10 +562,9 @@ Session Options
 
 .. option:: --retryWrites
 
-   Enables :ref:`retryable-writes`. Retryable writes are enabled by
-   default in :binary:`mongosh`. Retryable writes are disabled by
-   default in the legacy :binary:`mongo` shell. To disable retryable
-   writes, use :option:`--retryWrites=false <mongosh --retryWrites>`.
+   Enables :ref:`retryable-writes`.
+   
+   .. include:: /includes/legacy/legacy-retryable-writes.rst
 
    For more information on sessions, see :ref:`sessions`.
 
diff --git a/source/run-commands.txt b/source/run-commands.txt
@@ -108,20 +108,10 @@ You can also terminate a script from within the script code by calling the
 ``exit(<code>)`` command. For more information, refer to 
 :ref:`Terminate a Script on Error <mongosh-terminate-script>`.
 
-
 Command Exceptions
 ------------------
 
-In scenarios where the output of a command includes ``{ ok: 0 }``,
-``mongosh`` throws an exception and does not return the raw output from
-the server.
-
-.. note::
-
-   In the legacy ``mongo`` shell, when a command's output included ``{
-   ok: 0 }``, the behavior differs between commands. ``mongosh``
-   provides consistent behavior by always throwing an exception in these
-   scenarios.
+.. include:: /includes/legacy/legacy-command-exceptions.rst
 
 Clear the ``mongosh`` Console
 -----------------------------

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+For commands whose output includes ``{ ok: 0 }``, ``mongosh`` returns a
	`2`	`+consistent exception and omits the server raw output. The legacy`
	`3`	+``mongo`` shell returns output that varies for each command.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+The legacy ``mongo`` shell cannot access a script's file name or
	`2`	+directory in the ``load()`` method.
Original file line number	Diff line number	Diff line change
`@@ -613,12 +613,12 @@ The output is:`
`613`	`613`	`}`
`614`	`614`	`]`
`615`	`615`
	`616`	`+.. _mongosh-ejson-stringify-legacy-output:`
	`617`	`+`
`616`	`618`	Legacy ``tojsononeline()``
`617`	`619`	`~~~~~~~~~~~~~~~~~~~~~~~~~~`
`618`	`620`
`619`		-``mongosh`` formats query output differently than the deprecated
`620`		-``mongo`` shell. You may have scripts which rely on the old format. To
`621`		-reformat ``mongosh`` output on a single line, use ``EJSON.stringify()``.
	`621`	`+.. include:: /includes/legacy/legacy-output.rst`
`622`	`622`
`623`	`623`	Run a sample query in ``mongosh`` and ``mongo`` to see the different
`624`	`624`	`formats.`