NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[ADD] Upgrade documentation: How-to-guide for developers

Browse Source 
closes odoo/documentation#6757

Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
This commit is contained in:
Nathan Marotte (nama) 2023-11-17 13:07:25 +01:00 committed by Augusto Perez
parent 53656d7065
commit 44f4683519
4 changed files with 313 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
content/administration/upgrade.rst
View File

@ -39,10 +39,11 @@ An upgrade does not cover:
- Migrating from another ERP to Odoo
.. warning::
If your database contains a **custom module**, you must first upgrade its source code to be
compatible with the new version of Odoo **before upgrading**.
.. TODOUPG : once the page for developers is published, uncomment and link
.. :doc:`first upgrade its source code </developer/reference/upgrade>`
If your database contains custom modules, it cannot be upgraded until a version of your custom
modules is available for the target version of Odoo. For customers maintaining their own custom
modules, we recommend to parallelize the process by :ref:`requesting an upgraded database
<upgrade/request-test-database>` while also :doc:`upgrading the source code of your custom
modules </developer/howtos/upgrade_custom_db>`.
Upgrading in a nutshell
@ -51,15 +52,15 @@ Upgrading in a nutshell
#. Request an upgraded test database (see :ref:`obtaining an upgraded test database
<upgrade/request-test-database>`).
#. If applicable, upgrade the source code of your custom module to be compatible with the new
version of Odoo (see :doc:`/developer/howtos/upgrade_custom_db`).
#. Thoroughly test the upgraded database (see :ref:`testing the new version of the database
<upgrade/test_your_db>`).
#. Report any issue encountered during the testing to Odoo via the `support page
<https://odoo.com/help?stage=migration>`__.
#. (If applicable) : upgrade the source code of your custom module to be compatible with the new
version of Odoo.
#. Once all issues are resolved and you are confident that the upgraded database can be used as
your main database without any issues, plan the upgrade of your production database.
@ -69,9 +70,6 @@ Upgrading in a nutshell
#. Report any issue encountered during the upgrade to Odoo via the `support page
<https://odoo.com/help?stage=post_upgrade>`__.
.. TODOUPG: Once the page for developers is published, put this at 4)
.. (see :ref:`upgrading customizations <upgrade/upgrading_customizations>`).
.. _upgrade/request-test-database:
Obtaining an upgraded test database
@ -136,18 +134,13 @@ project <https://odoo.sh/project>`_.
file of the upgrade process can be found in your newly upgraded staging build by going to
:file:`~/logs/upgrade.log`.
.. note::
In databases where custom modules are installed, their source code
must be up-to-date with the target version of Odoo before the upgrade
can be performed. If there are none, the "update on commit" mode is
skipped, the upgraded database is built as soon as it is transferred from the upgrade
platform, and the upgrade mode is exited.
.. important::
In databases where custom modules are installed, their source code must be up-to-date with
the target version of Odoo before the upgrade can be performed. If there are none, the
"update on commit" mode is skipped, the upgraded database is built as soon as it is
transferred from the upgrade platform, and the upgrade mode is exited.
.. TODOUPG : once the page for developers is published, uncomment
.. Check out the :doc:`upgrade for developers'
.. documentation </developer/reference/upgrade>` for more information. In
.. addition, if a module is not needed after an upgrade, :ref:`you can
.. remove customizations <upgrade/remove_customizations>`.
Check out the :doc:`/developer/howtos/upgrade_custom_db` page for more information.
.. group-tab:: On-premise
@ -167,6 +160,11 @@ project <https://odoo.sh/project>`_.
An upgraded test database can also be requested via the `Upgrade page
<https://upgrade.odoo.com/>`_.
.. important::
In databases where custom modules are installed, their source code must be up-to-date with
the target version of Odoo before the upgrade can be performed. Check out the
:doc:`/developer/howtos/upgrade_custom_db` page for more information.
.. note::
- For security reasons, only the person who submitted the upgrade request can download it.
- For storage reasons, the database's copy is submitted without a filestore to the upgrade
@ -291,8 +289,8 @@ the upgrade at a time when the use of the database is minimal.
As the standard upgrade scripts and your database are constantly evolving, it is also recommended
to frequently request another upgraded test database to ensure that the upgrade process is
still successful, especially if it takes a long time to finish. Fully rehearsing the upgrade
process the day before upgrading the production database is also recommended.
still successful, especially if it takes a long time to finish. **Fully rehearsing the upgrade
process the day before upgrading the production database is also recommended.**
.. important::
- Going into production without first testing may lead to:
@ -337,9 +335,8 @@ exceptions.
The update of your custom modules must be successful to complete the entire upgrade process.
Make sure the status of your staging upgrade is :guilabel:`successful` before trying it in
production.
.. TODOUPG : once the page for developers is published, uncomment
.. More information on how to upgrade your custom modules can be found in the :ref:`upgrading customizations documentation <upgrade/upgrading_customizations>`.
production. More information on how to upgrade your custom modules can be found on
:doc:`/developer/howtos/upgrade_custom_db`.
.. group-tab:: On-premise

6
content/developer/howtos.rst
View File

@ -19,6 +19,7 @@ How-to guides
howtos/translations
howtos/website_themes
howtos/connect_device
howtos/upgrade_custom_db
.. cards::
@ -77,3 +78,8 @@ How-to guides
:target: howtos/connect_device
Learn how to enable a module to detect and communicate with an IoT device.
.. 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.

257
content/developer/howtos/upgrade_custom_db.rst Normal file
View File

@ -0,0 +1,257 @@
=============================
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. 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 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:
#. Stay supported
#. Get the latest features
#. Enjoy the performance improvement
#. Reduce the technical debt
#. Benefit from security improvements
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:
#. :ref:`Stop the devolopments and challenge them <upgrade_custom/stop_developments>`.
#. :ref:`Request an upgraded database <upgrade_custom/request_upgrade>`.
#. :ref:`Make your module installable on an empty database <upgrade_custom/empty_database>`.
#. :ref:`Make your module installable on the upgraded database <upgrade_custom/upgraded_database>`.
#. :ref:`Test extensively and do a rehearsal <upgrade_custom/testing_rehearsal>`.
#. :ref:`Upgrade the production database <upgrade_custom/production>`.
.. _upgrade_custom/stop_developments:
Step 1: Stop the developments
=============================
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 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
<https:/odoo.com/page/release-notes>`_.
.. _upgrade_custom/request_upgrade:
Step 2: Request an upgraded database
====================================
Once the developments have stopped for the custom modules and the implemented features have been
challenged to remove redundancy and unnecessary code, the next step is to request an upgraded test
database. To do so, follow the steps mentioned in :ref:`upgrade/request-test-database`, depending on
the hosting type of your database.
The purpose of this stage is not to start working with the custom modules in the upgraded database,
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.
.. _upgrade_custom/empty_database:
Step 3: 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 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 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>`
.. _upgrade_custom/empty_database/modules_installable:
Make custom modules installable
-------------------------------
The first step is to make the custom modules installable in the new Odoo version.
This means, starting by ensuring there are no tracebacks or warnings during their installation.
For this, install the custom modules, one by one, in an empty database of the new Odoo version and
fix the tracebacks and warnings that arise from that.
This process will help detect issues during the installation of the modules. For example:
- Invalid module dependencies.
- Syntax change: assets declaration, OWL updates, attrs.
- References to standard fields, models, views not existing anymore or renamed.
- Xpath that moved or were removed from views.
- Methods renamed or removed.
- ...
.. _upgrade_custom/empty_database/test_fixes:
Test and fixes
--------------
Once there are no more tracebacks when installing the modules, the next step is to test them.
Even if the custom modules are installable on an empty database, this does not guarantee there are
no errors during their execution. Because of this, we encourage to test thoroughly all the
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.
We recommend to test all the customization, especially the following elements:
- Views
- Email templates
- Reports
- Server actions and automated actions
- Changes in the standard workflows
- Computed fields
We also encourage to write automated tests to save time during the testing iterations, increase the
test coverage, and ensure that the changes and fixes introduced do not break the existing flows.
If there are tests already implemented in the customization, make sure they are upgraded to the new
Odoo version and run successfully, fixing issues that might be present.
.. _upgrade_custom/empty_database/clean_code:
Clean the code
--------------
At this stage of the upgrade process, we also suggest to clean the code as much as possible.
This includes:
- Remove redundant and unnecessary code.
- Remove features that are now part of Odoo standard, as described in
:ref:`upgrade_custom/stop_developments`.
- Clean commented code if it is not needed anymore.
- Refactor the code (functions, fields, views, reports, etc.) if needed.
.. _upgrade_custom/empty_database/standard_test:
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.
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.
In case there are standard test failing, we suggest to analyze the reason for their failure:
- The customization changes the standard workflow: Adapt the standard test to your workflow.
- The customization did not take into account a special flow: Adapt your customization to ensure it
works for all the standard workflows.
.. _upgrade_custom/upgraded_database:
Step 4: Upgraded database
=========================
Once the custom modules are installable and working properly in an empty database, it is time to
make them work on an :ref:`upgraded database <upgrade/request-test-database>`.
To make sure the custom code is working flawlessly in the new version, follow these steps:
- :ref:`upgrade_custom/upgraded_database/migrate_data`
- :ref:`upgrade_custom/upgraded_database/test_custom`
.. _upgrade_custom/upgraded_database/migrate_data:
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.
- 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 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 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.
.. _upgrade_custom/upgraded_database/test_custom:
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 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 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
data that needs to be updated due to changes in the new version, we recommend to use migration
scripts to do so.
.. _upgrade_custom/testing_rehearsal:
Step 5: 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 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 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:
Step 6: Production upgrade
==========================
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.

31
content/developer/reference/cli.rst
View File

@ -664,18 +664,41 @@ Here is a sample file:
Shell
=====
Odoo command-line also allows to launch odoo as a python console environment.
This enables direct interaction with the :ref:`orm <reference/orm>` and its functionalities.
The Odoo command line also allows launching Odoo as a Python console environment, enabling direct
interaction with the :ref:`orm <reference/orm>` and its functionalities.
.. code-block:: console
$ odoo-bin shell
.. example::
Adding an exclamation mark to all contacts' names:
.. code-block:: python
In [1]: records = env["res.partner"].search([])
In [2]: records
Out[2]: res.partner(14, 26, 33, 21, 10)
In [3]: for partner in records:
...: partner.name = "%s !" % partner.name
...:
In [4]: env.cr.commit()
.. important::
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.
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:`reference/orm/environment`
.. _reference/cmdline/scaffold: