[IMP] odoo.sh: update builds page

closes #15440

Signed-off-by: Xavier Platteau (xpl) <xpl@odoo.com>

Author: xpl-odoo

content/administration/odoo_sh/getting_started/builds.rst

@@ -1,124 +1,137 @@
-
-.. _odoosh-gettingstarted-builds:
-
 ======
 Builds
 ======
 
+In Odoo.sh, a build is a database loaded by an Odoo server (`odoo/odoo
+<https://github.com/odoo/odoo>`_ and `odoo/enterprise <https://github.com/odoo/enterprise>`_)
+running on a specific revision of your project repository in a containerized environment. Its
+purpose is to test the proper behavior of the server, the database, and the features associated with
+that revision.
+
+.. _odoo-sh/builds/overview:
+
 Overview
 ========
 
-In Odoo.sh, a build is considered as a database loaded by an Odoo server
-(`odoo/odoo <https://github.com/odoo/odoo>`_ & `odoo/enterprise
-<https://github.com/odoo/enterprise>`_) running on a specific revision of your project repository in
-a containerized environment. Its purpose is to test the well-behavior of the server, the database
-and the features with this revision.
-
-.. image:: builds/interface-builds.png
-   :align: center
+.. image:: builds/builds-overview.png
+   :alt: Overiew of the builds
 
-In this view, a row represents a branch, and a cell of a row represents a build of this branch.
+In the :guilabel:`Builds` overview, a row represents a branch, and a cell within that row represents
+a build of that branch.
 
-Most of the time, builds are created following pushes on your Github repository branches.
-They can be created as well when you do other operations,
-such as importing a database on Odoo.sh or asking a rebuild for a branch in your project.
+Most builds are created after pushes to your GitHub repository branches. They can also be created
+through other operations, such as importing a database on Odoo.sh or requesting a rebuild for a
+branch in your project.
 
-A build is considered successful if no errors or warnings come up during its creation.
-A successful build is highlighted in green.
+Builds can have three possible statuses:
 
-A build is considered failed if errors come up during its creation.
-A failed build is highlighted in red.
+- A build is considered **successful** if no errors or warnings occur during its creation.
+  Successful builds are highlighted in **green**.
+- A build is considered **almost successful** if warnings occur, but there are no errors. Almost
+  successful builds are highlighted in **yellow**.
+- A build is considered **failed** if errors occur during its creation. Failed builds are
+  highlighted in **red**.
 
-If warnings come up during the creation, but there are no errors, the build is considered almost
-successful. It is highlighted in yellow to notify the developer warnings were raised.
+.. note::
+   Builds do not always create a database from scratch. For instance, when pushing a change on the
+   production branch, the created build starts the server with your new revision and tries to load
+   the current production database on it.
 
-Builds do not always create a database from scratch. For instance, when pushing a change on the
-production branch, the build created just starts the server with your new revision and tries to load
-the current production database on it. If no errors come up, the build is considered successful, and
-otherwise failed.
+.. _odoo-sh/builds/stages:
 
 Stages
 ======
 
+.. _odoo-sh/builds/stages/production:
+
 Production
 ----------
 
-The first build of a production branch creates a database from scratch.
-If this build is successful, this database is considered as the production database of your project.
+The first build of a production branch creates a database from scratch. If this build is successful,
+this database will become the production database of your project.
+
+From then on, pushes to the production branch will create new builds that attempt to load the
+database using a server running the new revision.
 
-From then, pushes on the production branch will create new builds that attempt to load the database
-using a server running with the new revision.
+If the build is successful or almost successful, the production database will run with this build
+and its associated revision.
 
-If the build is successful, or has warnings but no errors, the production database will now run with
-this build, along with the revision associated to this build.
+If the build fails to load or update the database, the previous successful build is reused to load
+the database. In that case, the database continues to run using the previous successful revision.
 
-If the build fails to load or update the database, then the previous successful build is re-used to
-load the database, and therefore the database will run using a server running with the previous
-successful revision.
+.. note::
+   The build used to run the production database is always the first in the builds list. If a build
+   fails, it is placed after the build currently running the production database.
 
-The build used to run the production database is always the first of the builds list. If a build
-fails, it is put after the build currently running the production database.
+.. _odoo-sh/builds/stages/staging:
 
 Staging
 -------
 
-Staging builds duplicate the production database,
-and try to load this duplicate with the revisions of the staging branches.
+Staging builds duplicate the production database and attempt to load this copy using the revisions
+of the staging branches.
 
-Each time you push a new revision on a staging branch, the build created uses a new copy of the
-production database. The databases are not re-used between builds of the same branch. This ensures:
+Each time you push a new revision to a staging branch, the resulting build uses a fresh copy of the
+production database. Databases are not reused between builds of the same branch. This ensures that:
 
-* staging builds use databases that are close to what the production looks like, so you do not make
-  your tests with outdated data,
+- Staging builds use databases that closely match the current production state, so your tests are
+  not performed on outdated data.
+- You can freely experiment within a staging database. When you want to start over with a new copy
+  of the production database, you can request a rebuild.
 
-* you can play around as much as you want in the same staging database, and you can then ask for a
-  rebuild when you want to restart with a new copy of the production.
+However, this also means that if you make configuration changes in a staging database and do not
+apply them in production, those changes will not be present in the next build of the same staging
+branch.
 
-Nevertheless, this means that if you make configuration changes in staging databases and do not
-apply them in the production, they will not be passed on the next build of the same staging branch.
+.. _odoo-sh/builds/stages/development:
 
 Development
 -----------
 
-Development builds create new databases, load the demo data and run the unit tests.
+Development builds create new databases, load the demo data, and run the unit tests.
 
-A build will be considered failed and highlighted in red if tests fail during the installation,
-as they are meant to raise errors if something wrong occurs.
+A build will be considered failed if tests fail during installation, as they are designed to raise
+errors when something is wrong.
 
-If all tests pass, and there is no error, the build will be considered successful.
+If all tests pass and no errors occur, the build is considered successful.
 
-According to the list of modules to install and test, a development build can take up to 1 hour to
-be ready. This is due to the large number of tests set in the default Odoo modules suite.
+.. note::
+   Depending on the list of modules to install and test, a development build can take up to one hour
+   to be ready. This is due to the large number of tests included in the default Odoo module suite.
+
+.. _odoo-sh/builds/stages/features:
 
 Features
 ========
 
-The production branch will always appear first, and then the other branches are ordered by last
-build created. You can filter out the branches.
-
-.. image:: builds/interface-builds-branches.png
-   :align: center
+The production branch always appears first. Other branches are ordered by the time of their last
+created build. The stage highlighted in purple corresponds to the stage selected in the
+:guilabel:`Branches` menu.
 
-For each branch, you can access the last build's database using the *Connect* link and jump to the
-branch code using the *Github* link. For other branches than the production, you can create a new
-build which will use the latest revision of the branch using the link *rebuild*. This last link is
-not available when there is already a build in progress for the branch.
+.. tip::
+   You can filter branches using the search bar.
 
-.. image:: builds/interface-builds-build.png
-   :align: center
+.. image:: builds/branches-menu.png
+   :alt: The branches menu
 
-For each build, you can access the revision changes using the button with the Github icon. You can
-access the build's database as the administrator using the *Connect* button. Also, you can access
-the database with another user using the *Connect as* button, in the dropdown menu of the *Connect*
-button.
+For each branch, you can:
 
-.. _odoosh-gettingstarted-builds-download-dump:
+- Access the latest build's database by clicking :guilabel:`Connect`.
+- Jump to the branch's code by clicking :guilabel:`Github`.
+- Create a new build by clicking :guilabel:`Rebuild`. It uses the latest revision of the branch (it
+  is not available if a build is already in progress for that branch).
 
-.. image:: builds/interface-builds-build-dropdown.png
-   :align: center
+For each build, you can:
 
-.. _odoosh-gettingstarted-builds-dropdown-menu:
+- View the revision changes by clicking the :icon:`fa-github` (:guilabel:`GitHub`) icon.
+- Access the build's database as the administrator by clicking :guilabel:`Connect` or as another
+  user by clicking the :icon:`fa-caret-down` (:guilabel:`More Actions`) button next to
+  :guilabel:`Connect` and selecting :guilabel:`Connect as`.
+- Access the same tools as in the branches view by clicking the :icon:`fa-caret-down`
+  (:guilabel:`More Actions`) button next to :guilabel:`Connect` and selecting :guilabel:`Logs`,
+  :guilabel:`Web Shell`, :guilabel:`Editor`, :guilabel:`Outgoing e-mails` (for the staging and
+  development stages), :guilabel:`Monitoring`, and :guilabel:`Download DB dump` (for the production
+  and staging stages).
 
-In the dropdown menu of the build, you can access the same features than in :ref:`the branches view
-<odoo-sh/branches/tabs>`: *Logs*, *Web Shell*, *Editor*, *Outgoing e-mails*. You also
-have the possibility to *Download a dump* of the build's database.
+.. image:: builds/builds-options.png
+   :alt: A build's options

content/administration/odoo_sh/getting_started/builds/branches-menu.png

@@ -17,7 +17,7 @@ It also gives you the possibility to open terminals, Python consoles, Odoo Shell
 
 You can access the editor of a build through
 :ref:`the branches tabs <odoo-sh/branches/tabs>`,
-:ref:`the builds dropdown menu <odoosh-gettingstarted-builds-dropdown-menu>`
+:ref:`the builds dropdown menu <odoo-sh/builds/stages/features>`
 or by adding */odoo-sh/editor* to your build domain name
 (e.g. *https://odoo-addons-master-1.dev.odoo.com/odoo-sh/editor*).