[FIX] Upgrade documentation: Code review changes

Author: augustoPerez

content/developer/howtos.rst

@@ -86,7 +86,7 @@ How-to guides
 
       Learn how to enable a module to detect and communicate with an IoT device.
 
-   .. card:: Upgrading a customized database
+   .. card:: Upgrade a customized database
       :target: howtos/upgrade_custom_db
 
-      Learn how to upgrade a customized database, as well as the code and data of its custom modules.
+      Learn how to upgrade a customized database, as well as the code and data of its custom modules.

content/developer/howtos/upgrade_custom_db.rst

@@ -1,20 +1,15 @@
-:show-content:
-
-.. _upgrade_custom/upgrade_custom_db:
-
-===============================
-Upgrading a customized database
-===============================
+=============================
+Upgrade a customized database
+=============================
 
 Upgrading to a new version of Odoo can be challenging, especially if the database you work on
 contains custom modules. This page intent is to explain the technical process of upgrading a
-database with customized modules. For a standard overview, please refer to the
-:doc:`Upgrade documentation </administration/upgrade>`.
+database with customized modules. Refer to :doc:`Upgrade documentation </administration/upgrade>`
+for guidance on how to upgrade a database without customized modules.
 
 We consider a custom module, any module that extends the standard code of Odoo and that was not
-built with the Studio app. 
-Before upgrading those modules, or before asking for them to be upgraded, have a look at the
-:ref:`upgrade/sla` to make sure who's responsible for it.
+built with the Studio app. Before upgrading such a module, or before requesting its upgrade, have a
+look at the :ref:`upgrade/sla` to make sure who's responsible for it.
 
 While working on what we refer to as the **custom upgrade** of your database, keep in mind the goals
 of an upgrade:
@@ -25,9 +20,9 @@ of an upgrade:
 #. Reduce the technical debt
 #. Benefit from security improvements
 
-With every new version of Odoo, changes are introduced. These changes can have an impact modules on
-which customization have been developed. This is the reason why upgrading a database that contains
-custom modules requires additional steps in order to upgrade their source code.
+With every new version of Odoo, changes are introduced. These changes can impact modules on which
+customization have been developed. This is the reason why upgrading a database that contains custom
+modules requires additional steps in order to upgrade the source code.
 
 These are the steps to follow to upgrade customized databases:
 
@@ -44,16 +39,16 @@ These are the steps to follow to upgrade customized databases:
 Stop the developments
 =====================
 
-Starting an upgrade requires commitment and development resources need to be allocated to it. If
-developments keep being made at the same time, those features will need to be re-upgraded and tested
-everytime you change them. This is why we recommend a complete freeze of the codebase when starting
-the upgrade process. Needless to say, bug fixing is exempt from this recommendation.
+Starting an upgrade requires commitment and development resources. If developments keep being made
+at the same time, those features will need to be re-upgraded and tested every time you change them.
+This is why we recommend a complete freeze of the codebase when starting the upgrade process.
+Needless to say, bug fixing is exempt from this recommendation.
 
 Once you have stopped development, it is a good practice to assess the developments made and compare
 them with the features introduced between your current version and the version you are targeting.
-Challenge the developments as much as possible, find functionnal workarounds.
-Removing redundancy between your developments and the standard version of Odoo will lead to an eased
-upgrade process and reduce the technical debt.
+Challenge the developments as much as possible and find functional workarounds. Removing redundancy
+between your developments and the standard version of Odoo will lead to an eased
+upgrade process and reduce technical debt.
 
 .. note::
    You can find information on the changes between versions in the `Release Notes
@@ -74,7 +69,7 @@ The purpose of this stage is not to start working with the custom modules in the
 but to make sure the standard upgrade process works seamlessly, and the test database is delivered
 properly. If that's not the case, and the upgrade request fails, request the assistance of Odoo via
 the `support page <https://odoo.com/help?stage=migration>`_ by selecting the option related to
-testing the upgrade. 
+testing the upgrade.
 
 
 .. _upgrade_custom/empty_database:
@@ -83,22 +78,21 @@ Empty database
 ==============
 
 Before working on an upgraded test database, we recommend to make the custom developments work on an
-empty database in the targeted version of your upgrade. 
-This ensures that the customization is compatible with the new version of Odoo, allows to analyse
-how does it behave and interact with the new features, and guarantees that they will not cause any
-issue when upgrading the database.
+empty database in the targeted version of your upgrade. This ensures that the customization is
+compatible with the new version of Odoo, allows to analyze how it behaves and interacts with the new
+features, and guarantees that they will not cause any issues when upgrading the database.
 
-Making the custom modules work in an empty database also helps avoiding changes and wrong
-configurations that might be present on the production database (like studio customization,
+Making the custom modules work in an empty database also helps avoid changes and wrong
+configurations that might be present in the production database (like studio customization,
 customized website pages, email templates or translations). They are not intrinsically related to
 the custom modules and that can raise unwanted issues in this stage of the upgraded process.
 
 To make custom modules work on an empty database we advise to follow these steps:
 
-- :ref:`upgrade_custom/empty_database/modules_installable`
-- :ref:`upgrade_custom/empty_database/test_fixes`
-- :ref:`upgrade_custom/empty_database/clean_code`
-- :ref:`Make standard tests run successfully <upgrade_custom/empty_database/standard_test>`
+#. :ref:`upgrade_custom/empty_database/modules_installable`
+#. :ref:`upgrade_custom/empty_database/test_fixes`
+#. :ref:`upgrade_custom/empty_database/clean_code`
+#. :ref:`Make standard tests run successfully <upgrade_custom/empty_database/standard_test>`
 
 .. _upgrade_custom/empty_database/modules_installable:
 
@@ -131,9 +125,9 @@ customization to make sure everything is working as expected.
 
 This process will help detect further issues that are not identified during the module installation
 and can only be detected in runtime. For example, deprecated calls to standard python or OWL
-functions, non existing references to standard fields, etc.
+functions, non-existing references to standard fields, etc.
 
-We recommend to test all the customization, specially the following elements:
+We recommend to test all the customization, especially the following elements:
 
 - Views
 - Email templates
@@ -153,7 +147,7 @@ Clean the code
 --------------
 
 At this stage of the upgrade process, we also suggest to clean the code as much as possible.
-This includes: 
+This includes:
 
 - Remove redundant and unnecessary code.
 - Remove features that are now part of Odoo standard, as described in
@@ -167,7 +161,7 @@ Standard tests
 --------------
 
 Once the previous steps are completed, we advise to make sure all standard tests associated to the
-dependencies of the custom module pass. 
+dependencies of the custom module pass.
 Standard tests ensure the validation of the code logic and prevent data corruption.
 They will help you identify bugs or unwanted behavior before you work on your database.
 
@@ -199,16 +193,17 @@ Migrate the data
 During the upgrade of the custom modules, you might have to use migration scripts to reflect changes
 from the source code to their corresponding data.
 
-- Any technical data that was renamed during the upgrade of the custom code (models, fields, external
-  identifiers) should be renamed using migration scripts to avoid data loss during the module upgrade.
+- Any technical data that was renamed during the upgrade of the custom code (models, fields,
+  external identifiers) should be renamed using migration scripts to avoid data loss during the
+  module upgrade.
 - Data from standard models removed from the source code of the newer Odoo version and from the
   database during the standard upgrade process might need to be recovered from the old model table
-  if it is stil present.
+  if it is still present.
 
 Migration scripts can also be used to:
 
 - Ease the processing time of an upgrade. For example, to store the value of computed stored fields
-  on models with an excesive amount of records by using SQL queries.
+  on models with an excessive number of records by using SQL queries.
 - Recompute fields in case the computation of their value has changed.
 - Uninstall unwanted custom modules.
 - Correct faulty data or wrong configurations.
@@ -220,13 +215,13 @@ Test the custom modules
 
 To make sure the custom modules work properly with your data in the upgraded database, they need to
 be tested as well. This helps ensure both the standard and the custom data stored in the database
-are consistent and nothing was lost during the upgrade process.
+are consistent and that nothing was lost during the upgrade process.
 
 Things to pay attention to:
 
-- Views not working: During the upgrade, if a view causes issues because of it's content, it gets
-  disabled. You can find the information of disabled views on the :ref:`Upgraded report
-  <upgrade/upgrade_report>`. This views need to be activated again. To achieve this, we recommend
+- Views not working: During the upgrade, if a view causes issues because of its content, it gets
+  disabled. You can find the information on disabled views on the :ref:`Upgrade report
+  <upgrade/upgrade_report>`. This view needs to be activated again. To achieve this, we recommend
   the use of migration scripts.
 - :doc:`Module data <../tutorials/define_module_data>` not updated: Custom records that have the
   ``noupdate`` flag are not updated when upgrading the module in the new database. For the custom
@@ -240,23 +235,23 @@ Testing and rehearsal
 =====================
 
 When the custom modules are working properly in the upgraded database, it is crucial to do another
-round of testing to assess the database usability and detect any issue that might have gone
-unnoticed in previous tests. For further information about testing the upgraded database, check 
+round of testing to assess the database usability and detect any issues that might have gone
+unnoticed in previous tests. For further information about testing the upgraded database, check
 :ref:`upgrade/test_your_db`.
 
 As mentioned in :ref:`upgrade/upgrade-prod`, both standard upgrade scripts and your database are
 constantly evolving. Therefore it is highly recommended to frequently request new upgraded test
 databases and ensure that the upgrade process is still successful.
 
-In adition to that, make a full rehearsal of the upgrade process the day before upgrading the
-production database to avoid an undesired behavior during the upgrade and to detect any issue that
-might have ocurred with the migrated data.
+In addition to that, make a full rehearsal of the upgrade process the day before upgrading the
+production database to avoid undesired behavior during the upgrade and to detect any issue that
+might have occurred with the migrated data.
 
 
 .. _upgrade_custom/production:
 
 Production upgrade
 ==================
 
-Once you are confident about upgrading your production database, follow the process described on 
+Once you are confident about upgrading your production database, follow the process described on
 :ref:`upgrade/upgrade-prod`, depending on the hosting type of your database.

content/developer/reference/cli.rst

@@ -676,12 +676,7 @@ interaction with the :ref:`orm <reference/orm>` and its functionalities.
 
    $ odoo-bin shell
 
-.. option:: --shell-interface (ipython|ptpython|bpython|python)
-
-   Specify a preferred REPL to use in shell mode. This shell is started with the `env` variable
-   already initialized to be able to access the ORM and other Odoo modules.
-
-.. example:: Example of shell usage
+.. example::
 
    Adding an exclamation mark to all contacts' names:
 
@@ -702,8 +697,13 @@ interaction with the :ref:`orm <reference/orm>` and its functionalities.
       By default, the shell is running in transaction mode. This means that any change made to the
       database is rolled back when exiting the shell. To commit changes, use `env.cr.commit()`.
 
+.. option:: --shell-interface (ipython|ptpython|bpython|python)
+
+   Specify a preferred REPL to use in shell mode. This shell is started with the `env` variable
+   already initialized to be able to access the ORM and other Odoo modules.
+
 .. seealso::
-   :ref:`Environment documentation <reference/orm/environment>`
+   :ref:`reference/orm/environment`
 
 .. _reference/cmdline/scaffold:
 
@@ -944,4 +944,3 @@ containing community and enterprise.
 .. code-block:: console
 
    $ community/odoo-bin tsconfig --addons-path community/addons,community/odoo/addons,enterprise > tsconfig.json
-