Add compat.box_info_cluster_meaning

Author: p7nov

doc/reference/configuration/configuration_reference.rst

@@ -505,6 +505,8 @@ The ``compat`` section defines values of the :ref:`compat <compat-module>` modul
     -   ``new``: show the entire cluster
     -   ``old:``: show the current replica set
 
+    See also: :ref:`compat-option-box-info-cluster`
+
     |
     | Type: string
     | Possible values: 'new', 'old'

doc/reference/reference_lua/box_info/cluster.rst

@@ -13,6 +13,6 @@ box.info.cluster
 
     *   ``name`` -- the cluster name
 
-    See also: :ref:`compat.box_info_cluster_meaning <configuration_reference_compat_cluster_meaning>`
+    See also: :ref:`compat.box_info_cluster_meaning <compat-option-box-info-cluster>`
 
     :rtype: table

doc/reference/reference_lua/compat.rst

@@ -73,6 +73,7 @@ Below are the available ``compat`` options:
 * :doc:`sql_seq_scan_default <./compat/sql_seq_scan_default>`
 * :doc:`fiber_slice_default <./compat/fiber_slice_default>`
 * :doc:`binary_data_decoding <./compat/binary_data_decoding>`
+* :doc:`box_info_cluster_meaning <./compat/box_info_cluster_meaning>`
 
 ..  toctree::
     :hidden:

doc/reference/reference_lua/compat/box_info_cluster_meaning.rst

@@ -0,0 +1,72 @@
+.. _compat-option-box-info-cluster:
+
+Meaning of box.info.cluster
+===========================
+
+Option: ``box_info_cluster_meaning``
+
+Starting from version 3.0, the :ref:`box_info_cluster` table stores the information
+about the entire cluster. In earlier versions, it stored only the current replica set
+information. The ``box_info_cluster_meaning`` compat option allows to define the
+the scope of ``box.info.cluster``: the entire cluster or a single replica set.
+
+Old and new behavior
+--------------------
+
+New behavior: ``box.info.cluster`` displays information about the entire
+cluster with all its replica sets.
+
+..  code-block:: tarantoolsession
+
+    tarantool> compat.box_info_cluster_meaning = 'new'
+    ---
+    ...
+
+    tarantool> box.info.cluster
+    ---
+    - <cluster information>
+    ...
+
+    tarantool> box.info.replicaset
+    ---
+    - uuid: <replicaset uuid>
+    - <... other attributes of the replicaset>
+    ...
+
+.. note::
+
+    In the new behavior, :ref:`box_info_replicaset` is equivalent to the old ``box.info.cluster``.
+
+Old behavior: ``box.info.cluster`` displays information about the current replica set.
+
+..  code-block:: tarantoolsession
+
+    tarantool> compat.box_info_cluster_meaning = 'old'
+    ---
+    ...
+
+    tarantool> box.info.cluster
+    ---
+    - uuid: <replicaset uuid>
+    - <... other attributes of the replicaset>
+    ...
+
+    tarantool> box.info.replicaset (= nil on < 3.0.0)
+    ---
+    - uuid: <replicaset uuid>
+    - <... other attributes of the replicaset>
+    ...
+
+Known compatibility issues
+--------------------------
+
+``vshard`` versions earlier than 0.1.24 do not support the new behavior.
+
+
+Detecting issues in your codebase
+---------------------------------
+
+Look for all usages of ``box.info.cluster``, ``info.cluster``, and
+``.cluster``, ``['cluster']``, ``["cluster"]`` in the application code
+written before the change. To make it work the same way on Tarantool 3.0 or later,
+replace the ``cluster`` key with ``replicaset``.