Apply suggestions from review

* Some text is repeated. This is because Sphinx cannot correctly
  enumerate lists when list items come from different `include` files.

* Clarify the "replica" term in the instructions

* Clarify how to change the master in a replica set

* Add cross-links to guide the user

* Bring indents in accordance with the style guide

* Clarify how to run code to fix xlogs when upgrading from 1.6 to 1.10

Author: patiencedaur

doc/book/admin/_includes/1.6-to-2.x-condition.rst

@@ -5,8 +5,8 @@ under 1.10 or 2.x for a while. A few configuration parameters are also renamed.
 
 To perform a **live** upgrade from Tarantool 1.6 to a more recent version,
 like :doc:`2.8.4 </release/2.8.4>`, :doc:`2.10.1 </release/2.10.1>` and such,
-it is necessary to take an intermediate step by upgrading 1.6 -> 1.10 -> 2.x.
-This is the only way to perform the upgrade without downtime.
+it is necessary to take an intermediate step by upgrading 1.6 -> **1.10** -> 2.x.
+This is the only way to perform the upgrade **without downtime**.
 
 However, a direct upgrade of a replica set from 1.6 to 2.x is also possible, but only
 **with downtime**.

doc/book/admin/_includes/upgrade_procedure.rst

@@ -1,21 +1,46 @@
-1. Pick any replica in the replica set.
+1.  Pick any read-only instance in the replica set.
 
-2. Upgrade this replica to the new Tarantool version. See details in
-   :ref:`Upgrading a Tarantool instance <admin-upgrades_instance>`.
+2.  Upgrade this replica to the new Tarantool version. See details in
+    :ref:`Upgrading Tarantool on a standalone instance <admin-upgrades_instance>`.
+    This requires stopping the instance for a while,
+    which won't interrupt the replica set operation.
+    When the upgraded replica is up again, it will synchronize with the other instances in the replica set
+    so that the data are consistent across all the instances.
 
-3. Make sure the replica connected to the rest of the replica set just fine:
+3.  Make sure the upgraded replica is running and connected to the rest of the replica set just fine.
+    To do this, run ``box.info.replication`` in the instance's console
+    and check the output table for values like ``upstream``, ``downstream``, and ``lag``.
 
-   ..  code-block:: tarantoolsession
+    For each instance ``id``, there are ``upstream`` and ``downstream`` values.
+    Both of them should have the value ``follow``, except on the instance where you run this code.
+    This means that the replicas are connected and there are no errors in the data flow.
 
-       box.info.replication[id].upstream
-       box.info.replication[id].downstream
-      
-   The ``status`` field in both outputs should have the value ``follow``.
+    The value of the ``lag`` field can be less or equal than ``box.cfg.replication_timeout``,
+    but it can also be moderately larger.
+    For example, if ``box.cfg.replication_timeout`` is 1 second and the write load on the master is high,
+    it's generally OK to have a lag of about 10 seconds on the master.
+    It is up to the user to decide what lag values are fine.
 
-4. :ref:`Upgrade <admin-upgrades_instance>` all the replicas by repeating steps 1--3
-   until only the master keeps running the old Tarantool version.
+4.  :ref:`Upgrade <admin-upgrades_instance>` all the read-only instances by repeating steps 1--3
+    until only the master keeps running the old Tarantool version.
 
-5. Make one of the updated replicas the new master.
-   Check that it continues following and being followed by all other replicas.
+5.  Make one of the updated replicas the new master:
+    
+    -   If the replica set is using asynchronous replication without
+        :ref:`RAFT-based leader elections <repl_leader_elect>`,
+        first run ``box.cfg{ read_only = true}`` on the old master
+        and then run ``box.cfg{ read_only = false }`` on the replica that will be the new master.
 
-6. :ref:`Upgrade <admin-upgrades_instance>` the former master.
+    -   If the replica set is using :ref:`synchronous replication <repl_sync>` or
+        :ref:`RAFT-based leader elections <repl_leader_elect>`,
+        run ``box.ctl.promote()`` on the new master and then run
+        ``box.cfg{ election_mode = 'voter' }`` on the old master.
+        This will automatically change the ``read_only`` statuses on the instances.
+
+    -   For a Cartridge replica set, it is possible to select the new master in the web UI.
+
+    There is no need to restart the new master.
+
+    Check that the new master continues following and being followed by all other replicas, similarly to step 3.
+
+6.  :ref:`Upgrade <admin-upgrades_instance>` the former master, which is now a read-only instance.

doc/book/admin/upgrades.rst

@@ -1,12 +1,12 @@
-.. _admin-upgrades:
+..  _admin-upgrades:
 
 Upgrades
 ========
 
 For information about backwards compatibility,
 see the :ref:`compatibility guarantees <compatibility_guarantees>` description.
 
-.. _admin-upgrades_instance:
+..  _admin-upgrades_instance:
 
 Upgrading Tarantool on a standalone instance
 --------------------------------------------
@@ -16,18 +16,25 @@ Notice that this will **always imply a downtime**.
 To upgrade **without downtime**, you need several Tarantool servers running in a
 replication cluster (see :ref:`below <admin-upgrades_replication_cluster>`).
 
-1. Stop the Tarantool server.
+#.  Stop the Tarantool server.
 
-2. Make a copy of all data (see an appropriate hot backup procedure in
-   :ref:`Backups <admin-backups>`) and the package from which the current (old)
-   version was installed (for rollback purposes).
+#.  Make a copy of all data (see an appropriate hot backup procedure in
+    :ref:`Backups <admin-backups>`) and the package from which the current (old)
+    version was installed (for rollback purposes).
 
-3. Update the Tarantool server. See installation instructions at Tarantool
-   `download page <http://tarantool.org/download.html>`_.
+#.  Update the Tarantool server. See installation instructions at Tarantool
+    `download page <http://tarantool.org/download.html>`_.
 
-After that, make sure to :ref:`finish the upgrade properly <admin-upgrades_db>`.
+#.  Run :ref:`box.schema.upgrade() <box_schema-upgrade>` on the new master.
+    This will update the Tarantool system spaces to match the currently installed version of Tarantool.
+    There is no need  to run ``box.schema.upgrade()`` on every node:
+    changes are propagated to other nodes via the regular replication mechanism.
 
-.. _admin-upgrades_replication_cluster:
+#.  Update your application files, if needed.
+
+#.  Launch the updated Tarantool server using ``tarantoolctl``, ``tt``, or ``systemctl``.
+
+..  _admin-upgrades_replication_cluster:
 
 Upgrading Tarantool in a replica set with no downtime
 -----------------------------------------------------
@@ -47,82 +54,50 @@ instructions for individual versions :ref:`in the list below <admin-upgrades_ver
 Preparations
 ~~~~~~~~~~~~
 
-#. Check the replica set health by running the following code on every instance:
+#.  Check the replica set health by running the following code on every instance:
 
-   ..  code-block:: tarantoolsession
+    ..  code-block:: tarantoolsession
 
-       box.info.ro -- "false" at least on one instance
-       box.info.status -- should be "running"
+        box.info.ro -- "false" at least on one instance
+        box.info.status -- should be "running"
  
-   If all instances have ``box.info.ro = true``, this means there are no writable nodes.
-   If you're running Tarantool :doc:`v. 2.10.0 </release/2.10.0>` or later,
-   you can find out the reason by running ``box.info.ro_reason``.
-   If it has the value ``orphan``, the instance doesn't see the rest of the replica set.
-   Similarly, if ``box.info.status`` has the value ``orphan``, the instance doesn't see the rest of the replica set.
-   First resolve the replication issues and only then continue.
-
-   If you're running Cartridge, you can also check node health in the UI.
-
-#. Make sure each replica connected to the rest of the replica set.
-   Run ``box.info.replication`` and check the output table.
-   For each instance ``id``, there are ``upstream`` and ``downstream`` values.
-   Both of them should have the value ``follow``, except on the instance where you run this code.
-   This means that the replicas are connected and there are no errors in the data flow.
-
-   The value of the ``lag`` field can be less or equal than ``box.cfg.replication_timeout``,
-   but it can also be moderately larger.
-   For example, if ``box.cfg.replication_timeout`` is 1 second and the write load on the master is high,
-   it's generally OK to have a lag of about 10 seconds on the master.
-   It is up to the user to decide what lag values are fine.
-
+    If all instances have ``box.info.ro = true``, this means there are no writable nodes.
+    If you're running Tarantool :doc:`v. 2.10.0 </release/2.10.0>` or later,
+    you can find out the reason by running ``box.info.ro_reason``.
+    If it has the value ``orphan``, the instance doesn't see the rest of the replica set.
+    Similarly, if ``box.info.status`` has the value ``orphan``, the instance doesn't see the rest of the replica set.
+    First resolve the replication issues and only then continue.
+
+    If you're running Cartridge, you can also check node health in the UI.
+
+#.  Make sure each replica is connected to the rest of the replica set.
+    To do this, run ``box.info.replication`` in the instance's console
+    and check the output table for values like ``upstream``, ``downstream``, and ``lag``.
+
+    For each instance ``id``, there are ``upstream`` and ``downstream`` values.
+    Both of them should have the value ``follow``, except on the instance where you run this code.
+    This means that the replicas are connected and there are no errors in the data flow.
+
+    The value of the ``lag`` field can be less or equal than ``box.cfg.replication_timeout``,
+    but it can also be moderately larger.
+    For example, if ``box.cfg.replication_timeout`` is 1 second and the write load on the master is high,
+    it's generally OK to have a lag of about 10 seconds on the master.
+    It is up to the user to decide what lag values are fine.
+    
 If the replica set is healthy, proceed to the upgrade.
 
 Upgrade procedure
 ~~~~~~~~~~~~~~~~~
 
 ..  include:: ./_includes/upgrade_procedure.rst
 
-After upgrading the replica set, make sure to run ``box.schema.upgrade()`` on the new master
-as described below in the section ":ref:`Finishing the upgrade <admin-upgrades_db>`".
-There is no need  to run ``box.schema.upgrade()`` on every node:
-changes are propagated to other nodes via the regular replication mechanism.
-
-Finally, run ``box.snapshot()`` on every node in the replica set
-to make sure that the replicas immediately see the upgraded database state in case of restart.
-
-.. _admin-upgrades_db:
-
-Finalizing the upgrade
-----------------------
-
-1.  If you created a database with an older Tarantool version and have now installed
-    a newer version, make the request ``box.schema.upgrade()``. This updates
-    Tarantool system spaces to match the currently installed version of Tarantool.
-
-    For example, here is what happens when you run ``box.schema.upgrade()`` with a
-    database created with Tarantool version 1.6.4 to version 1.7.2 (only a small
-    part of the output is shown):
-
-    .. code-block:: tarantoolsession
-
-       tarantool> box.schema.upgrade()
-       alter index primary on _space set options to {"unique":true}, parts to [[0,"unsigned"]]
-       alter space _schema set options to {}
-       create view _vindex...
-       grant read access to 'public' role for _vindex view
-       set schema version to 1.7.0
-       ---
-       ...
- 
-    You can also put the request ``box.schema.upgrade()``
-    inside a :doc:`box.once() </reference/reference_lua/box_once>` function in your Tarantool
-    :ref:`initialization file <index-init_label>`.
-    On startup, this will create new system spaces, update data type names (for example,
-    ``num`` -> ``unsigned``, ``str`` -> ``string``) and options in Tarantool system spaces.
-
-2.  Update your application files, if needed.
+7.  Run :ref:`box.schema.upgrade() <box_schema-upgrade>` on the new master.
+    This will update the Tarantool system spaces to match the currently installed version of Tarantool.
+    There is no need  to run ``box.schema.upgrade()`` on every node:
+    changes are propagated to other nodes via the regular replication mechanism.
 
-3.  Launch the updated Tarantool server using ``tarantoolctl``, ``tt``, or ``systemctl``.
+8.  Run ``box.snapshot()`` on every node in the replica set
+    to make sure that the replicas immediately see the upgraded database state in case of restart.
 
 
 ..  _admin-upgrades_version_specifics:

doc/book/admin/upgrades/1.6-1.10.rst

@@ -8,23 +8,27 @@ when upgrading a replica set from Tarantool 1.6 to 1.10.
 
 ..  include:: ../_includes/1.6-to-2.x-condition.rst
 
-Let's first reiterate the upgrade procedure for any Tarantool version:
+The procedure of live upgrade from 1.6 to 1.10 is similar to the general upgrade procedure,
+which is as follows:
 
 ..  include:: ../_includes/upgrade_procedure.rst
 
-7.  Run ``box.schema.upgrade()`` on the new master
-    as described in the section ":ref:`Finishing the upgrade <admin-upgrades_db>`".
+7.  Run :ref:`box.schema.upgrade() <box_schema-upgrade>` on the new master.
+    This will update the Tarantool system spaces to match the currently installed version of Tarantool.
     There is no need  to run ``box.schema.upgrade()`` on every node:
     changes are propagated to other nodes via the regular replication mechanism.
 
+..  _admin-upgrades-1.6-1.10-step_8:
+
 8.  Run ``box.snapshot()`` on every node in the replica set
     to make sure that the replicas immediately see the upgraded database state in case of restart.
 
 What's different when upgrading from Tarantool 1.6:
 
 **Step 2:** Tarantool 1.10+ fails to recover from 1.6 xlogs, unless ``box.cfg{force_recovery = true}`` is set.
 There is some small difference between 1.6 and 1.10 xlogs, which makes 1.6 xlogs appear erroneous to 1.10+ instances.
-In order to work around this, start the instance in ``force_recovery`` mode.
+In order to work around this, start the instance in ``force_recovery`` mode. To do so, add the line
+``force_recovery = true`` to the file where the instance is initialized -- for example, to ``init.lua``.
 
 **Step 3:** New Tarantool nodes follow 1.6 nodes just fine,
 but some 1.6 nodes might disconnect from new nodes with an ER_LOADING error.
@@ -38,10 +42,11 @@ This is not critical, the error goes away when replication on 1.6 is restarted:
 
 **Step 7:** There was a breaking change between 1.6 and 1.10 --
 in 1.6, the field type ``num`` was an alias to ``number``, and in 1.10, ``num`` is converted to ``unsigned``.
-This means that after ``box.schema.upgrade()`` is performed on master,
+This means that after ``box.schema.upgrade()`` is performed on the master,
 the user might have some spaces with ``unsigned`` fields containing non-unsigned values:
 ``double``, ``int``, and so on.
-This will make the snapshot inconsistent, unless an extra action is performed after ``box.schema.upgrade()``:
+This will make the snapshot inconsistent, unless an extra action is performed after ``box.schema.upgrade()``.
+Run this code in the Tarantool console on the new master:
 
 ..  code-block:: lua
 
@@ -51,9 +56,10 @@ This will make the snapshot inconsistent, unless an extra action is performed af
     a[problematic_field_no].type = 'number'
     box.space.problematic_space:format(a)
 
-Once this is performed on the master, it's safe to proceed to step 8, making snapshot on every node.
+Once this is performed on the master, it's safe to proceed to
+:ref:`step 8 <admin-upgrades-1.6-1.10-step_8>`, making a snapshot on every node.
 
 **Step 8:** The user might be concerned with snapshot size in 1.10 --
 it's drastically smaller than the one created by 1.6 (for example, ~300 Mb vs. 6 Gb in some corner cases).
-There's nothing to worry about.
+There is nothing to worry about.
 Tarantool 1.6 didn't compress snapshots, while Tarantool 1.10 and above does that.

doc/book/admin/upgrades/1.6-2.0-downtime.rst

@@ -1,7 +1,7 @@
 ..  _admin-upgrades-1.6-2.x_downtime:
 
-Upgrade from 1.6 directly to 2.x
-================================
+Upgrade from 1.6 directly to 2.x with downtime
+==============================================
 
 ..  include:: ../_includes/1.6-to-2.x-condition.rst