From fa078752d7cfa7083cd236a0831507d2be8c9aa8 Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Fri, 17 Nov 2023 13:07:25 +0100 Subject: [PATCH 01/12] [ADD] Upgrade documentation : technical --- content/developer/reference.rst | 1 + content/developer/reference/cli.rst | 51 ++- content/developer/reference/upgrade.rst | 427 ++++++++++++++++++++++++ 3 files changed, 463 insertions(+), 16 deletions(-) create mode 100644 content/developer/reference/upgrade.rst diff --git a/content/developer/reference.rst b/content/developer/reference.rst index 96ab9eb529..4e53b3cce7 100644 --- a/content/developer/reference.rst +++ b/content/developer/reference.rst @@ -14,3 +14,4 @@ Reference reference/cli reference/external_api reference/extract_api + reference/upgrade diff --git a/content/developer/reference/cli.rst b/content/developer/reference/cli.rst index dcfef28f58..bd8c3c60cf 100644 --- a/content/developer/reference/cli.rst +++ b/content/developer/reference/cli.rst @@ -136,13 +136,9 @@ Running the server stops the server after its initialization. -.. option:: --geoip-city-db +.. option:: --geoip-db - Absolute path to the GeoIP City database file. - -.. option:: --geoip-country-db - - Absolute path to the GeoIP Country database file. + Absolute path to the GeoIP database file. .. _reference/cmdline/testing: @@ -290,7 +286,7 @@ Database .. option:: --unaccent - Try to enable the unaccent extension when creating new databases + Use the unaccent function provided by the database when available. .. _reference/cmdline/server/emails: @@ -559,18 +555,18 @@ Multiprocessing .. option:: --limit-memory-soft - Maximum allowed virtual memory per worker in bytes. If the limit is exceeded, + Maximum allowed virtual memory per worker. If the limit is exceeded, the worker is killed and recycled at the end of the current request. - Defaults to *2048MiB (2048\*1024\*1024B)*. + Defaults to *2048MiB*. .. option:: --limit-memory-hard - Hard limit on virtual memory in bytes, any worker exceeding the limit will be + Hard limit on virtual memory, any worker exceeding the limit will be immediately killed without waiting for the end of the current request processing. - Defaults to *2560MiB (2560\*1024\*1024B)*. + Defaults to *2560MiB*. .. option:: --limit-time-cpu @@ -655,9 +651,8 @@ 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 ` and its functionalities. - +The Odoo command line also allows launching Odoo as a Python console environment, enabling direct +interaction with the :ref:`orm ` and its functionalities. .. code-block:: console @@ -665,8 +660,32 @@ This enables direct interaction with the :ref:`orm ` and its func .. 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. + +.. example:: Example of shell usage + + 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()`. + +.. seealso:: + :ref:`Environment documentation ` .. _reference/cmdline/scaffold: @@ -906,4 +925,4 @@ containing community and enterprise. .. code-block:: console - $ community/odoo-bin tsconfig --addons-path community/addons,community/odoo/addons,enterprise > tsconfig.json + $ community/odoo-bin tsconfig --addons-path community/addons,community/odoo/addons,enterprise > tsconfig.json \ No newline at end of file diff --git a/content/developer/reference/upgrade.rst b/content/developer/reference/upgrade.rst new file mode 100644 index 0000000000..3d1d3522e3 --- /dev/null +++ b/content/developer/reference/upgrade.rst @@ -0,0 +1,427 @@ +====================== +Upgrade for developers +====================== + +The upgrade process +=================== + +TODOUPG re-analyze to see if necessary + +#. Exporting the database to a file +#. Uploading the file to the upgrade server +#. Running a series of :ref:`standard migration scripts ` to + upgrade standard modules +#. Downloading the upgraded database +#. Importing the file into a database +#. (*If applicable*) :ref:`Custom migration scripts ` + developed by the maintainer of your custom modules are ran to upgrade them. + +.. _reference/upgrade/migration-scripts: + +Migration scripts +================= + +A migration script is a Python file containing a function called `migrate`, which the upgrade +process invokes at the appropriate time. Typically, this function executes one or multiple SQL +queries and can also access Odoo's ORM, as well as the `upgrade-util package +`__. + +.. example:: + Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model + in the standard code of Odoo. This change required the development of standard migration scripts + to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no + data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets + removed by another standard migration script. + +.. seealso:: + `DjangoProject.com documentation: Migrations + `_ + +.. spoiler:: Two migration scripts: adding "!" at the end of partners' names + + .. code-block:: python + + import logging + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + cr.execute( + """ + UPDATE res_partner + SET name = name || '!' + """ + ) + _logger.info("Updated %s partners", cr.rowcount) + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + env = util.env(cr) + + partners = env["res.partner"].search([]) + for partner in partners: + partner.name += "!" + + _logger.info("Updated %s partners", len(partners)) + +.. spoiler:: Migration script: fixing a Studio view + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + with util.edit_view(cr, "studio_customization.odoo_studio_project__e2f15f1a-2bdb-4003-a36e-ed731a1b9fae") as arch: + node = arch.xpath("""//xpath[@expr="//group[field[@name='activity_summary']]"]""")[0] + node.attrib["expr"] = "//field[@name='activity_summary']" + +.. note:: + Only Odoo's employees can modify migration scripts in the standard upgrade process on the upgrade + server. Third-party developers can develop custom migration scripts for their custom modules. + +Positioning a migration script +------------------------------ + +Migration scripts are executed depending on their module, the version of Odoo, the version of the +module, the phase of the migration script, and its name. The path of the file should follow this +template: :file:`/migrations/./{pre|post|end}-*.py` + +- :file:`` corresponds to the folder name of a module. For example, :file:`account` for + the Accounting module, or :file:`sale_subscription` for the Subscriptions module. +- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). +- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the + `Accounting module in Odoo 16 `_). +- :file:`` corresponds to :ref:`the phase of the migration script + `. +- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in + which it is executed for that module, version, and phase. + +.. _upgrade/migration-scripts-phases: + +Phases of migration scripts +--------------------------- + +The upgrade process consists of three phases for each version of each module: + + #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at + that time. + #. The post-phase, after the module and its dependencies are loaded and upgraded. + #. The end-phase, after all modules have been upgraded for that version. + +.. note:: + If you are unsure which phase to use, use the end-phase. + +Migration scripts are grouped according to the first part of their filenames into the corresponding +phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before +:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then +executed according to their lexical order. + +.. spoiler:: Execution order of example scripts for one module in one version + + - :file:`pre-zzz.py` + - :file:`pre-~do_something.py` + - :file:`post--testing.py` + - :file:`post-01-zzz.py` + - :file:`post-migrate.py` + - :file:`post-other_module.py` + - :file:`post-~migrate.py` + - :file:`end--migrate.py` + - :file:`end-01-migrate.py` + - :file:`end-aaa.py` + - :file:`end-~migrate.py` + +.. _upgrade/upgrading_customizations: + +Upgrading customizations +======================== + +The source code of custom modules maintained by third parties must be upgraded to be compatible with +each new version of Odoo. This usually requires a static analysis of the code to find all the +references of deprecated elements. However, it can also be done by installing the module and fixing +the errors that occur during the installation. + +Information on the changes between versions can be found in the `release notes +`_ and the :ref:`upgrade report `. + +.. seealso:: + - :ref:`reference/views` + - :ref:`reference/fields` + - :ref:`reference/orm/models` + +.. _upgrade/comparing_customizations: + +Comparing customizations to the new version +------------------------------------------- + +As many new features are added with each new version, some customizations may become obsolete when +equivalent features become part of the standard version of Odoo. + +Therefore, exploring the new features and comparing them with your customizations is recommended. +Removing unnecessary customizations reduces the work needed to maintain and upgrade your database. + +.. _upgrade/remove_customizations: + +Removing customizations +----------------------- + +Customizations that have become redundant with the release of a new version of Odoo can be removed +from your database with a :ref:`migration script ` using the +`uninstall_module` method from the `upgrade-util package `__. +This method renames the field and the column in the database but does not impact views, reports, +filters, mail templates, automated and server actions, etc., that refer to those fields. Those +references must be found and removed from the database, as well as in the same migration script. + +.. important:: + :ref:`Testing your database ` is crucial, especially when uninstalling a + custom module. Any customized view, report, filter, mail template, automated and server actions, + etc., referring to an uninstall field will prevent them from working correctly and might block + your processes in certain situations. + +.. seealso:: + :ref:`upgrade/comparing_customizations` + +Upgrading custom fields and their data +-------------------------------------- + +Any custom field that has a reference to a modified standard field must be adapted to the new +version of Odoo. To find the corresponding field in the new version, we recommend looking at its +properties and finding a field with matching properties. You can also use the :ref:`upgrade report +` and the `release notes `_ to support +your search. + +.. example:: + In Odoo 12 and before, the `account.invoice` model had a field named `refund_invoice_id` (`source + code `_), + which is absent on the `account.move` model after Odoo 13. This field was renamed to + `reversed_entry_id` during the upgrade process. It is possible to find this information by + searching for another Many2one field in `account.move` related to `account.move`, for example, + `in Odoo 16 `_. + +.. note:: + Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. + However, this only renames the field and column names. Therefore, custom views, reports, field + relations, automated actions, etc., might still refer to the old field name and need to be + updated in the migration script as well. + +Upgrading models and methods definitions +---------------------------------------- + +Upgrading custom models consists mainly of ensuring that the module name and its inheritances +are correct. The :ref:`upgrade report ` and the `release notes +`_ can contain helpful information concerning various standard +models being changed or renamed. + +.. example:: + The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 `_ + that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 `_. + +If a custom model overrides standard methods, you must ensure that their name still matches the +name of the method they are overriding. In case of changes, you can search the method's source code +in the new version to find its new name. If the method has been refactored, the source code might +not exactly match, and a manual search is then required. + +Upgrading views definitions +--------------------------- + +Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's +`` tag, which can happen during a module update or when rendering it. + +Most of the time, the incompatibility of a custom view is expressed via an error when parsing the +view, which can happen during the update of a module or when rendering it. + +Custom views for custom models only require upgrading if the custom model has been changed. In +contrast, custom views inheriting from standard views can be impacted by changes in the standard +views. In this case, the custom views' source code requires an upgrade to be compatible with the new +version of its parent view. This can be done by retargetting the various Xpath expressions to match +an equivalent element that might have been moved or renamed. + +Upgrading data +============== + +Errors during upgrade +--------------------- + +Suppose some critical data is removed during the standard upgrade process or an exception is raised, +stopping the upgrade process. In that case, a migration script must be injected during the process +to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the +Upgrade server, and custom migration scripts are only executed after the standard process succeeds. + +Errors can be due to two things: + + - An inconsistency in the data of the original database, in which case the underlying issue can be + fixed in production **after testing on a duplicated database** + - An error during the generation of data during the upgrade, in which case the `intervention of a + developer of the Upgrade team `_ is required to fix the issue and + restart the upgrade process + +.. spoiler:: Access error + + Access errors are raised when a user tries to access a record without the proper access rights. + During upgrades, the administrator user (`ID=2`) is used to perform all operations and, + therefore, should be able to access all records. + + .. example:: + `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) + records.` + + This message means the administrator (`ID=2`) does not have the access rights to read a + record of the model `hr.applicant` (Recruitment app). The same error message can appear when + trying to access a record from the web interface without the access rights to do so. + + The error can be solved by giving back all administrator access rights to the administrator, + even for custom groups or record rules. + +.. spoiler:: Validation error + + Validation errors are raised by various safeguards implemented in the source code of Odoo, + ensuring data is consistent. The message is usually accompanied by the traceback, which might + display which record is causing the error. + + .. example:: + `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax + using it.` + + This error is raised in `this part of the code `_. + It is possible to conclude that this error appears if there is a record of the `account.tax` + model for which the country set on the tax group differs from the country set on the tax + itself. + + Therefore, fixing the error requires searching for faulty taxes and fixing them by setting + their country to the country of their tax group (or vice versa), either manually via the web + page of the database, with PSQL queries, or with the :ref:`Odoo shell + `, depending on the hosting type. + +.. seealso:: + - :ref:`reference/exceptions` + - :doc:`Data access restriction <../tutorials/restrict_data_access>` + - :doc:`Access rights <../../applications/general/users/access_rights>` + - :doc:`User management <../../applications/general/users/manage_users>` + +Upgrading server, scheduled, and automated actions +-------------------------------------------------- + +References to fields in server, scheduled, and automated actions might be broken due to changes in +the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a +new Record*, or *Update the Record*. + +Those actions are susceptible to being removed by the standard upgrade process, requiring +`intervention from an Odoo developer `_. Otherwise, it can be fixed +with a custom `migration script `_. + +.. note:: + To prevent actions from being removed, it is possible to preemptively change the reference(s) to + a field before upgrading and restoring them after the upgrade process. + +.. seealso:: + :ref:`Server actions ` + +Upgrading studio customizations +=============================== + +.. _reference/upgrade/studio_views: + +Studio views +------------ + +The upgrade process archives Odoo Studio view customizations if an issue is detected with their +definition. The logs will display a warning, but the upgrade process will not halt. + +Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` +attribute) and show the complete error message, allowing you to find the broken Xpath expression. It +is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. + +Views can also be deleted from the database during the upgrade if their corresponding model becomes +invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after +the standard upgrade process, but their deletion can be prevented by `requesting assistance from a +developer of the Upgrade team `_. + +.. note:: + Custom views generated by Studio do not always contain immutable targets in their Xpath + definition. When developing custom views with Studio, changing the generated Xpath to improve + their robustness is a good practice. + +.. spoiler:: The custom view caused validation issues + + This warning is raised when a custom view created with Studio is not valid anymore due to Xpath + targets that cannot be found in the parent view. + + .. example:: + + .. code-block:: console + + 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view + + View name: Odoo Studio: crm.lead.tree.opportunity customization + Error context: + view: ir.ui.view(1137,) + xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 + view.model: crm.lead + view.parent: ir.ui.view(902,) + + 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. + Disabling it for the migration ... + + This issue can be fixed by changing the Xpath target (the `expr` attribute) with a + :ref:`migration script ` using the `edit_view` method from + the `upgrade-util package `_ to match the same element in + the new version of the view. + +.. seealso:: + - :ref:`reference/exceptions` + - :ref:`reference/views` + - :ref:`reference/views/inheritance` + +Studio fields +------------- + +In case of invalid references on a field created by Studio, such as the `model`, `related`, or +`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be +accessible for the custom migration scripts or on the upgraded database. + +This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be +recoverable once the upgrade of the production database is completed. + +.. example:: + In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with + `account.move` and was then subsequently removed. The standard migration scripts took care of + moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the + columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not + automatically moved. Once the data migration to `account_move` was completed, the + `account_invoice` table was dropped, with all the custom data still in it. + +In those situations, you can `request assistance from Odoo `_ to upgrade +your custom fields during the standard upgrade process by specifying the following: + +- The name of the field(s) removed from your database +- The name of the model(s) they were on +- The reason why they were removed (model removed, relation removed, related field removed, etc.) +- Which new model, relation, or related field they should be on +- Any additional information that could help retrieve the fields + +Studio reports +-------------- + +The mechanism behind reports customization generated by Studio is the same as the one used for +:ref:`reference/upgrade/studio_views`. + +For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, +meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying +the content of the upgraded report and writing it over the content of the duplicated report. Note +that this might lead to issues with the Studio customizations made on the duplicate, such as +invalid Xpath targets. + +.. important:: + The code of a duplicated report should not be modified to ensure it is upgradable. If you need + to modify the code of a report, it is recommended to customize it with Studio. \ No newline at end of file From 30d53729e9956708cdc0e27e1fc22d012e3a19db Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Thu, 23 Nov 2023 07:44:59 +0100 Subject: [PATCH 02/12] [ADD] Upgrade documentation technical --- content/developer/howtos.rst | 6 + .../howtos/upgrade/migration_scripts.rst | 125 +++++ .../upgrade/upgrading_customizations.rst | 104 +++++ content/developer/howtos/upgrade_module.rst | 228 ++++++++++ content/developer/reference/upgrade.rst | 427 ------------------ 5 files changed, 463 insertions(+), 427 deletions(-) create mode 100644 content/developer/howtos/upgrade/migration_scripts.rst create mode 100644 content/developer/howtos/upgrade/upgrading_customizations.rst create mode 100644 content/developer/howtos/upgrade_module.rst delete mode 100644 content/developer/reference/upgrade.rst diff --git a/content/developer/howtos.rst b/content/developer/howtos.rst index 6a38860ac3..8f60f60632 100644 --- a/content/developer/howtos.rst +++ b/content/developer/howtos.rst @@ -20,6 +20,7 @@ How-to guides howtos/translations howtos/website_themes howtos/connect_device + howtos/upgrade_module .. cards:: @@ -84,3 +85,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 custom module + :target: howtos/upgrade_module + + Learn how to upgrade a custom module to a new version of Odoo. \ No newline at end of file diff --git a/content/developer/howtos/upgrade/migration_scripts.rst b/content/developer/howtos/upgrade/migration_scripts.rst new file mode 100644 index 0000000000..38b45cfc31 --- /dev/null +++ b/content/developer/howtos/upgrade/migration_scripts.rst @@ -0,0 +1,125 @@ + +================= +Migration scripts +================= + +A migration script is a Python file containing a function called `migrate`, which the upgrade +process invokes at the appropriate time. Typically, this function executes one or multiple SQL +queries and can also access Odoo's ORM, as well as the `upgrade-util package +`__. + +.. example:: + Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model + in the standard code of Odoo. This change required the development of standard migration scripts + to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no + data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets + removed by another standard migration script. + +.. seealso:: + `DjangoProject.com documentation: Migrations + `_ + +.. spoiler:: Two migration scripts: adding "!" at the end of partners' names + + .. code-block:: python + + import logging + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + cr.execute( + """ + UPDATE res_partner + SET name = name || '!' + """ + ) + _logger.info("Updated %s partners", cr.rowcount) + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + env = util.env(cr) + + partners = env["res.partner"].search([]) + for partner in partners: + partner.name += "!" + + _logger.info("Updated %s partners", len(partners)) + +.. spoiler:: Migration script: fixing a Studio view + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + with util.edit_view(cr, "studio_customization.odoo_studio_project__e2f15f1a-2bdb-4003-a36e-ed731a1b9fae") as arch: + node = arch.xpath("""//xpath[@expr="//group[field[@name='activity_summary']]"]""")[0] + node.attrib["expr"] = "//field[@name='activity_summary']" + +.. note:: + Only Odoo's employees can modify migration scripts in the standard upgrade process on the upgrade + server. Third-party developers can develop custom migration scripts for their custom modules. + +Positioning a migration script +------------------------------ + +Migration scripts are executed depending on their module, the version of Odoo, the version of the +module, the phase of the migration script, and its name. The path of the file should follow this +template: :file:`/migrations/./{pre|post|end}-*.py` + +- :file:`` corresponds to the folder name of a module. For example, :file:`account` for + the Accounting module, or :file:`sale_subscription` for the Subscriptions module. +- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). +- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the + `Accounting module in Odoo 16 `_). +- :file:`` corresponds to :ref:`the phase of the migration script + `. +- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in + which it is executed for that module, version, and phase. + +.. _upgrade/migration-scripts-phases: + +Phases of migration scripts +--------------------------- + +The upgrade process consists of three phases for each version of each module: + + #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at + that time. + #. The post-phase, after the module and its dependencies are loaded and upgraded. + #. The end-phase, after all modules have been upgraded for that version. + +.. note:: + If you are unsure which phase to use, use the end-phase. + +Migration scripts are grouped according to the first part of their filenames into the corresponding +phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before +:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then +executed according to their lexical order. + +.. spoiler:: Execution order of example scripts for one module in one version + + - :file:`pre-zzz.py` + - :file:`pre-~do_something.py` + - :file:`post--testing.py` + - :file:`post-01-zzz.py` + - :file:`post-migrate.py` + - :file:`post-other_module.py` + - :file:`post-~migrate.py` + - :file:`end--migrate.py` + - :file:`end-01-migrate.py` + - :file:`end-aaa.py` + - :file:`end-~migrate.py` \ No newline at end of file diff --git a/content/developer/howtos/upgrade/upgrading_customizations.rst b/content/developer/howtos/upgrade/upgrading_customizations.rst new file mode 100644 index 0000000000..374c212c2b --- /dev/null +++ b/content/developer/howtos/upgrade/upgrading_customizations.rst @@ -0,0 +1,104 @@ + +======================== +Upgrading customizations +======================== + +The source code of custom modules maintained by third parties must be upgraded to be compatible with +each new version of Odoo. This usually requires a static analysis of the code to find all the +references of deprecated elements. However, it can also be done by installing the module and fixing +the errors that occur during the installation. + +Information on the changes between versions can be found in the `release notes +`_ and the :ref:`upgrade report `. + +.. seealso:: + - :ref:`reference/views` + - :ref:`reference/fields` + - :ref:`reference/orm/models` + +.. _upgrade/comparing_customizations: + +Comparing customizations to the new version +------------------------------------------- + +As many new features are added with each new version, some customizations may become obsolete when +equivalent features become part of the standard version of Odoo. + +Therefore, exploring the new features and comparing them with your customizations is recommended. +Removing unnecessary customizations reduces the work needed to maintain and upgrade your database. + +.. _upgrade/remove_customizations: + +Removing customizations +----------------------- + +Customizations that have become redundant with the release of a new version of Odoo can be removed +from your database with a :ref:`migration script ` using the +`uninstall_module` method from the `upgrade-util package `__. +This method renames the field and the column in the database but does not impact views, reports, +filters, mail templates, automated and server actions, etc., that refer to those fields. Those +references must be found and removed from the database, as well as in the same migration script. + +.. important:: + :ref:`Testing your database ` is crucial, especially when uninstalling a + custom module. Any customized view, report, filter, mail template, automated and server actions, + etc., referring to an uninstall field will prevent them from working correctly and might block + your processes in certain situations. + +.. seealso:: + :ref:`upgrade/comparing_customizations` + +Upgrading custom fields and their data +-------------------------------------- + +Any custom field that has a reference to a modified standard field must be adapted to the new +version of Odoo. To find the corresponding field in the new version, we recommend looking at its +properties and finding a field with matching properties. You can also use the :ref:`upgrade report +` and the `release notes `_ to support +your search. + +.. example:: + In Odoo 12 and before, the `account.invoice` model had a field named `refund_invoice_id` (`source + code `_), + which is absent on the `account.move` model after Odoo 13. This field was renamed to + `reversed_entry_id` during the upgrade process. It is possible to find this information by + searching for another Many2one field in `account.move` related to `account.move`, for example, + `in Odoo 16 `_. + +.. note:: + Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. + However, this only renames the field and column names. Therefore, custom views, reports, field + relations, automated actions, etc., might still refer to the old field name and need to be + updated in the migration script as well. + +Upgrading models and methods definitions +---------------------------------------- + +Upgrading custom models consists mainly of ensuring that the module name and its inheritances +are correct. The :ref:`upgrade report ` and the `release notes +`_ can contain helpful information concerning various standard +models being changed or renamed. + +.. example:: + The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 `_ + that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 `_. + +If a custom model overrides standard methods, you must ensure that their name still matches the +name of the method they are overriding. In case of changes, you can search the method's source code +in the new version to find its new name. If the method has been refactored, the source code might +not exactly match, and a manual search is then required. + +Upgrading views definitions +--------------------------- + +Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's +`` tag, which can happen during a module update or when rendering it. + +Most of the time, the incompatibility of a custom view is expressed via an error when parsing the +view, which can happen during the update of a module or when rendering it. + +Custom views for custom models only require upgrading if the custom model has been changed. In +contrast, custom views inheriting from standard views can be impacted by changes in the standard +views. In this case, the custom views' source code requires an upgrade to be compatible with the new +version of its parent view. This can be done by retargetting the various Xpath expressions to match +an equivalent element that might have been moved or renamed. \ No newline at end of file diff --git a/content/developer/howtos/upgrade_module.rst b/content/developer/howtos/upgrade_module.rst new file mode 100644 index 0000000000..0bed26e3c7 --- /dev/null +++ b/content/developer/howtos/upgrade_module.rst @@ -0,0 +1,228 @@ +:show-content: +:hide-page-toc: +:show-toc: + +====================== +Upgrade for developers +====================== + +.. note:: + This page is intended to explain the technical aspects of Upgrading. For a more + general overview, please refer to the :ref:`upgrade documentation `. + +For a custom module to be used in a database running the new version of Odoo, a new version of its +source code be compatible with the latest changes in the source code of Odoo must bereleased. +Those changes usually include fields, models, methods, or views being renamed or refactored. + +Renaming references might not be enough, as the :ref:`ORM ` would not be able to +differenciate a field being deleted and another being created, from a simple renaming of a field. +Therefore, you might have to write :ref:`custom migration scripts ` +to reflect certain changes in the source code of your custom modules to their corresponding data. + +For the standard modules of Odoo, the new version of its source code, with their migration +scripts, are published by Odoo alongside the release of the new version, while for custom modules, +the new version with its migration scripts must be developed by the maintainer of the module. + +.. important:: + When committing to upgrading custom modules, it is crucial to halt the development of new + features since they would have to be upgraded as well, and might create new issues during the + upgrade process. Once the new version of your module has been released, you may resume the + development. + +.. seealso:: + `Upgrade-util package `_ + +In a nutshell, upgrading your customizations consists of: + +#. Halting the development of new customizations +#. Requesting an upgraded database and upgrading the custom modules' source code +#. Testing the upgraded modules on a new database, to catch any issue with the code +#. Testing the upgraded database with the new version of its modules, to catch any issue with the + data + +.. toctree:: + :maxdepth: 2 + + upgrade/migration_scripts + upgrade/upgrading_customizations + +TODO : bottom of this page moved to its own how to page + +Upgrading data +============== + +Errors during upgrade +--------------------- + +Suppose some critical data is removed during the standard upgrade process or an exception is raised, +stopping the upgrade process. In that case, a migration script must be injected during the process +to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the +Upgrade server, and custom migration scripts are only executed after the standard process succeeds. + +Errors can be due to two things: + + - An inconsistency in the data of the original database, in which case the underlying issue can be + fixed in production **after testing on a duplicated database** + - An error during the generation of data during the upgrade, in which case the `intervention of a + developer of the Upgrade team `_ is required to fix the issue and + restart the upgrade process + +.. spoiler:: Access error + + Access errors are raised when a user tries to access a record without the proper access rights. + During upgrades, the administrator user (`ID=2`) is used to perform all operations and, + therefore, should be able to access all records. + + .. example:: + `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) + records.` + + This message means the administrator (`ID=2`) does not have the access rights to read a + record of the model `hr.applicant` (Recruitment app). The same error message can appear when + trying to access a record from the web interface without the access rights to do so. + + The error can be solved by giving back all administrator access rights to the administrator, + even for custom groups or record rules. + +.. spoiler:: Validation error + + Validation errors are raised by various safeguards implemented in the source code of Odoo, + ensuring data is consistent. The message is usually accompanied by the traceback, which might + display which record is causing the error. + + .. example:: + `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax + using it.` + + This error is raised in `this part of the code `_. + It is possible to conclude that this error appears if there is a record of the `account.tax` + model for which the country set on the tax group differs from the country set on the tax + itself. + + Therefore, fixing the error requires searching for faulty taxes and fixing them by setting + their country to the country of their tax group (or vice versa), either manually via the web + page of the database, with PSQL queries, or with the :ref:`Odoo shell + `, depending on the hosting type. + +.. seealso:: + - :ref:`reference/exceptions` + - :doc:`Data access restriction <../tutorials/restrict_data_access>` + - :doc:`Access rights <../../applications/general/users/access_rights>` + - :doc:`User management <../../applications/general/users/manage_users>` + +Upgrading server, scheduled, and automated actions +-------------------------------------------------- + +References to fields in server, scheduled, and automated actions might be broken due to changes in +the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a +new Record*, or *Update the Record*. + +Those actions are susceptible to being removed by the standard upgrade process, requiring +`intervention from an Odoo developer `_. Otherwise, it can be fixed +with a custom `migration script `_. + +.. note:: + To prevent actions from being removed, it is possible to preemptively change the reference(s) to + a field before upgrading and restoring them after the upgrade process. + +.. seealso:: + :ref:`Server actions ` + +Upgrading studio customizations +=============================== + +.. _reference/upgrade/studio_views: + +Studio views +------------ + +The upgrade process archives Odoo Studio view customizations if an issue is detected with their +definition. The logs will display a warning, but the upgrade process will not halt. + +Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` +attribute) and show the complete error message, allowing you to find the broken Xpath expression. It +is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. + +Views can also be deleted from the database during the upgrade if their corresponding model becomes +invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after +the standard upgrade process, but their deletion can be prevented by `requesting assistance from a +developer of the Upgrade team `_. + +.. note:: + Custom views generated by Studio do not always contain immutable targets in their Xpath + definition. When developing custom views with Studio, changing the generated Xpath to improve + their robustness is a good practice. + +.. spoiler:: The custom view caused validation issues + + This warning is raised when a custom view created with Studio is not valid anymore due to Xpath + targets that cannot be found in the parent view. + + .. example:: + + .. code-block:: console + + 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view + + View name: Odoo Studio: crm.lead.tree.opportunity customization + Error context: + view: ir.ui.view(1137,) + xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 + view.model: crm.lead + view.parent: ir.ui.view(902,) + + 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. + Disabling it for the migration ... + + This issue can be fixed by changing the Xpath target (the `expr` attribute) with a + :ref:`migration script ` using the `edit_view` method from + the `upgrade-util package `_ to match the same element in + the new version of the view. + +.. seealso:: + - :ref:`reference/exceptions` + - :ref:`reference/views` + - :ref:`reference/views/inheritance` + +Studio fields +------------- + +In case of invalid references on a field created by Studio, such as the `model`, `related`, or +`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be +accessible for the custom migration scripts or on the upgraded database. + +This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be +recoverable once the upgrade of the production database is completed. + +.. example:: + In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with + `account.move` and was then subsequently removed. The standard migration scripts took care of + moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the + columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not + automatically moved. Once the data migration to `account_move` was completed, the + `account_invoice` table was dropped, with all the custom data still in it. + +In those situations, you can `request assistance from Odoo `_ to upgrade +your custom fields during the standard upgrade process by specifying the following: + +- The name of the field(s) removed from your database +- The name of the model(s) they were on +- The reason why they were removed (model removed, relation removed, related field removed, etc.) +- Which new model, relation, or related field they should be on +- Any additional information that could help retrieve the fields + +Studio reports +-------------- + +The mechanism behind reports customization generated by Studio is the same as the one used for +:ref:`reference/upgrade/studio_views`. + +For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, +meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying +the content of the upgraded report and writing it over the content of the duplicated report. Note +that this might lead to issues with the Studio customizations made on the duplicate, such as +invalid Xpath targets. + +.. important:: + The code of a duplicated report should not be modified to ensure it is upgradable. If you need + to modify the code of a report, it is recommended to customize it with Studio. \ No newline at end of file diff --git a/content/developer/reference/upgrade.rst b/content/developer/reference/upgrade.rst deleted file mode 100644 index 3d1d3522e3..0000000000 --- a/content/developer/reference/upgrade.rst +++ /dev/null @@ -1,427 +0,0 @@ -====================== -Upgrade for developers -====================== - -The upgrade process -=================== - -TODOUPG re-analyze to see if necessary - -#. Exporting the database to a file -#. Uploading the file to the upgrade server -#. Running a series of :ref:`standard migration scripts ` to - upgrade standard modules -#. Downloading the upgraded database -#. Importing the file into a database -#. (*If applicable*) :ref:`Custom migration scripts ` - developed by the maintainer of your custom modules are ran to upgrade them. - -.. _reference/upgrade/migration-scripts: - -Migration scripts -================= - -A migration script is a Python file containing a function called `migrate`, which the upgrade -process invokes at the appropriate time. Typically, this function executes one or multiple SQL -queries and can also access Odoo's ORM, as well as the `upgrade-util package -`__. - -.. example:: - Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model - in the standard code of Odoo. This change required the development of standard migration scripts - to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no - data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets - removed by another standard migration script. - -.. seealso:: - `DjangoProject.com documentation: Migrations - `_ - -.. spoiler:: Two migration scripts: adding "!" at the end of partners' names - - .. code-block:: python - - import logging - - _logger = logging.getLogger(__name__) - - - def migrate(cr, version): - cr.execute( - """ - UPDATE res_partner - SET name = name || '!' - """ - ) - _logger.info("Updated %s partners", cr.rowcount) - - .. code-block:: python - - import logging - from odoo.upgrade import util - - _logger = logging.getLogger(__name__) - - - def migrate(cr, version): - env = util.env(cr) - - partners = env["res.partner"].search([]) - for partner in partners: - partner.name += "!" - - _logger.info("Updated %s partners", len(partners)) - -.. spoiler:: Migration script: fixing a Studio view - - .. code-block:: python - - import logging - from odoo.upgrade import util - - _logger = logging.getLogger(__name__) - - - def migrate(cr, version): - with util.edit_view(cr, "studio_customization.odoo_studio_project__e2f15f1a-2bdb-4003-a36e-ed731a1b9fae") as arch: - node = arch.xpath("""//xpath[@expr="//group[field[@name='activity_summary']]"]""")[0] - node.attrib["expr"] = "//field[@name='activity_summary']" - -.. note:: - Only Odoo's employees can modify migration scripts in the standard upgrade process on the upgrade - server. Third-party developers can develop custom migration scripts for their custom modules. - -Positioning a migration script ------------------------------- - -Migration scripts are executed depending on their module, the version of Odoo, the version of the -module, the phase of the migration script, and its name. The path of the file should follow this -template: :file:`/migrations/./{pre|post|end}-*.py` - -- :file:`` corresponds to the folder name of a module. For example, :file:`account` for - the Accounting module, or :file:`sale_subscription` for the Subscriptions module. -- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). -- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the - `Accounting module in Odoo 16 `_). -- :file:`` corresponds to :ref:`the phase of the migration script - `. -- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in - which it is executed for that module, version, and phase. - -.. _upgrade/migration-scripts-phases: - -Phases of migration scripts ---------------------------- - -The upgrade process consists of three phases for each version of each module: - - #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at - that time. - #. The post-phase, after the module and its dependencies are loaded and upgraded. - #. The end-phase, after all modules have been upgraded for that version. - -.. note:: - If you are unsure which phase to use, use the end-phase. - -Migration scripts are grouped according to the first part of their filenames into the corresponding -phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before -:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then -executed according to their lexical order. - -.. spoiler:: Execution order of example scripts for one module in one version - - - :file:`pre-zzz.py` - - :file:`pre-~do_something.py` - - :file:`post--testing.py` - - :file:`post-01-zzz.py` - - :file:`post-migrate.py` - - :file:`post-other_module.py` - - :file:`post-~migrate.py` - - :file:`end--migrate.py` - - :file:`end-01-migrate.py` - - :file:`end-aaa.py` - - :file:`end-~migrate.py` - -.. _upgrade/upgrading_customizations: - -Upgrading customizations -======================== - -The source code of custom modules maintained by third parties must be upgraded to be compatible with -each new version of Odoo. This usually requires a static analysis of the code to find all the -references of deprecated elements. However, it can also be done by installing the module and fixing -the errors that occur during the installation. - -Information on the changes between versions can be found in the `release notes -`_ and the :ref:`upgrade report `. - -.. seealso:: - - :ref:`reference/views` - - :ref:`reference/fields` - - :ref:`reference/orm/models` - -.. _upgrade/comparing_customizations: - -Comparing customizations to the new version -------------------------------------------- - -As many new features are added with each new version, some customizations may become obsolete when -equivalent features become part of the standard version of Odoo. - -Therefore, exploring the new features and comparing them with your customizations is recommended. -Removing unnecessary customizations reduces the work needed to maintain and upgrade your database. - -.. _upgrade/remove_customizations: - -Removing customizations ------------------------ - -Customizations that have become redundant with the release of a new version of Odoo can be removed -from your database with a :ref:`migration script ` using the -`uninstall_module` method from the `upgrade-util package `__. -This method renames the field and the column in the database but does not impact views, reports, -filters, mail templates, automated and server actions, etc., that refer to those fields. Those -references must be found and removed from the database, as well as in the same migration script. - -.. important:: - :ref:`Testing your database ` is crucial, especially when uninstalling a - custom module. Any customized view, report, filter, mail template, automated and server actions, - etc., referring to an uninstall field will prevent them from working correctly and might block - your processes in certain situations. - -.. seealso:: - :ref:`upgrade/comparing_customizations` - -Upgrading custom fields and their data --------------------------------------- - -Any custom field that has a reference to a modified standard field must be adapted to the new -version of Odoo. To find the corresponding field in the new version, we recommend looking at its -properties and finding a field with matching properties. You can also use the :ref:`upgrade report -` and the `release notes `_ to support -your search. - -.. example:: - In Odoo 12 and before, the `account.invoice` model had a field named `refund_invoice_id` (`source - code `_), - which is absent on the `account.move` model after Odoo 13. This field was renamed to - `reversed_entry_id` during the upgrade process. It is possible to find this information by - searching for another Many2one field in `account.move` related to `account.move`, for example, - `in Odoo 16 `_. - -.. note:: - Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. - However, this only renames the field and column names. Therefore, custom views, reports, field - relations, automated actions, etc., might still refer to the old field name and need to be - updated in the migration script as well. - -Upgrading models and methods definitions ----------------------------------------- - -Upgrading custom models consists mainly of ensuring that the module name and its inheritances -are correct. The :ref:`upgrade report ` and the `release notes -`_ can contain helpful information concerning various standard -models being changed or renamed. - -.. example:: - The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 `_ - that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 `_. - -If a custom model overrides standard methods, you must ensure that their name still matches the -name of the method they are overriding. In case of changes, you can search the method's source code -in the new version to find its new name. If the method has been refactored, the source code might -not exactly match, and a manual search is then required. - -Upgrading views definitions ---------------------------- - -Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's -`` tag, which can happen during a module update or when rendering it. - -Most of the time, the incompatibility of a custom view is expressed via an error when parsing the -view, which can happen during the update of a module or when rendering it. - -Custom views for custom models only require upgrading if the custom model has been changed. In -contrast, custom views inheriting from standard views can be impacted by changes in the standard -views. In this case, the custom views' source code requires an upgrade to be compatible with the new -version of its parent view. This can be done by retargetting the various Xpath expressions to match -an equivalent element that might have been moved or renamed. - -Upgrading data -============== - -Errors during upgrade ---------------------- - -Suppose some critical data is removed during the standard upgrade process or an exception is raised, -stopping the upgrade process. In that case, a migration script must be injected during the process -to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the -Upgrade server, and custom migration scripts are only executed after the standard process succeeds. - -Errors can be due to two things: - - - An inconsistency in the data of the original database, in which case the underlying issue can be - fixed in production **after testing on a duplicated database** - - An error during the generation of data during the upgrade, in which case the `intervention of a - developer of the Upgrade team `_ is required to fix the issue and - restart the upgrade process - -.. spoiler:: Access error - - Access errors are raised when a user tries to access a record without the proper access rights. - During upgrades, the administrator user (`ID=2`) is used to perform all operations and, - therefore, should be able to access all records. - - .. example:: - `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) - records.` - - This message means the administrator (`ID=2`) does not have the access rights to read a - record of the model `hr.applicant` (Recruitment app). The same error message can appear when - trying to access a record from the web interface without the access rights to do so. - - The error can be solved by giving back all administrator access rights to the administrator, - even for custom groups or record rules. - -.. spoiler:: Validation error - - Validation errors are raised by various safeguards implemented in the source code of Odoo, - ensuring data is consistent. The message is usually accompanied by the traceback, which might - display which record is causing the error. - - .. example:: - `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax - using it.` - - This error is raised in `this part of the code `_. - It is possible to conclude that this error appears if there is a record of the `account.tax` - model for which the country set on the tax group differs from the country set on the tax - itself. - - Therefore, fixing the error requires searching for faulty taxes and fixing them by setting - their country to the country of their tax group (or vice versa), either manually via the web - page of the database, with PSQL queries, or with the :ref:`Odoo shell - `, depending on the hosting type. - -.. seealso:: - - :ref:`reference/exceptions` - - :doc:`Data access restriction <../tutorials/restrict_data_access>` - - :doc:`Access rights <../../applications/general/users/access_rights>` - - :doc:`User management <../../applications/general/users/manage_users>` - -Upgrading server, scheduled, and automated actions --------------------------------------------------- - -References to fields in server, scheduled, and automated actions might be broken due to changes in -the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a -new Record*, or *Update the Record*. - -Those actions are susceptible to being removed by the standard upgrade process, requiring -`intervention from an Odoo developer `_. Otherwise, it can be fixed -with a custom `migration script `_. - -.. note:: - To prevent actions from being removed, it is possible to preemptively change the reference(s) to - a field before upgrading and restoring them after the upgrade process. - -.. seealso:: - :ref:`Server actions ` - -Upgrading studio customizations -=============================== - -.. _reference/upgrade/studio_views: - -Studio views ------------- - -The upgrade process archives Odoo Studio view customizations if an issue is detected with their -definition. The logs will display a warning, but the upgrade process will not halt. - -Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` -attribute) and show the complete error message, allowing you to find the broken Xpath expression. It -is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. - -Views can also be deleted from the database during the upgrade if their corresponding model becomes -invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after -the standard upgrade process, but their deletion can be prevented by `requesting assistance from a -developer of the Upgrade team `_. - -.. note:: - Custom views generated by Studio do not always contain immutable targets in their Xpath - definition. When developing custom views with Studio, changing the generated Xpath to improve - their robustness is a good practice. - -.. spoiler:: The custom view caused validation issues - - This warning is raised when a custom view created with Studio is not valid anymore due to Xpath - targets that cannot be found in the parent view. - - .. example:: - - .. code-block:: console - - 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view - - View name: Odoo Studio: crm.lead.tree.opportunity customization - Error context: - view: ir.ui.view(1137,) - xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 - view.model: crm.lead - view.parent: ir.ui.view(902,) - - 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. - Disabling it for the migration ... - - This issue can be fixed by changing the Xpath target (the `expr` attribute) with a - :ref:`migration script ` using the `edit_view` method from - the `upgrade-util package `_ to match the same element in - the new version of the view. - -.. seealso:: - - :ref:`reference/exceptions` - - :ref:`reference/views` - - :ref:`reference/views/inheritance` - -Studio fields -------------- - -In case of invalid references on a field created by Studio, such as the `model`, `related`, or -`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be -accessible for the custom migration scripts or on the upgraded database. - -This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be -recoverable once the upgrade of the production database is completed. - -.. example:: - In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with - `account.move` and was then subsequently removed. The standard migration scripts took care of - moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the - columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not - automatically moved. Once the data migration to `account_move` was completed, the - `account_invoice` table was dropped, with all the custom data still in it. - -In those situations, you can `request assistance from Odoo `_ to upgrade -your custom fields during the standard upgrade process by specifying the following: - -- The name of the field(s) removed from your database -- The name of the model(s) they were on -- The reason why they were removed (model removed, relation removed, related field removed, etc.) -- Which new model, relation, or related field they should be on -- Any additional information that could help retrieve the fields - -Studio reports --------------- - -The mechanism behind reports customization generated by Studio is the same as the one used for -:ref:`reference/upgrade/studio_views`. - -For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, -meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying -the content of the upgraded report and writing it over the content of the duplicated report. Note -that this might lead to issues with the Studio customizations made on the duplicate, such as -invalid Xpath targets. - -.. important:: - The code of a duplicated report should not be modified to ensure it is upgradable. If you need - to modify the code of a report, it is recommended to customize it with Studio. \ No newline at end of file From 595eabed75a2dd6c8c78b0a4cc72912183d5a79f Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Thu, 23 Nov 2023 08:07:25 +0100 Subject: [PATCH 03/12] [IMP] Upgrade link technical doc --- content/administration/upgrade.rst | 16 ++++++++-------- content/developer/howtos.rst | 6 +++--- .../{upgrade_module.rst => upgrade_modules.rst} | 0 3 files changed, 11 insertions(+), 11 deletions(-) rename content/developer/howtos/{upgrade_module.rst => upgrade_modules.rst} (100%) diff --git a/content/administration/upgrade.rst b/content/administration/upgrade.rst index 153773268f..31c6ea6879 100644 --- a/content/administration/upgrade.rst +++ b/content/administration/upgrade.rst @@ -39,8 +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**. + 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 + ` while also :ref:`upgrading the source code of your custom + modules `. .. TODOUPG : once the page for developers is published, uncomment and link .. :doc:`first upgrade its source code ` @@ -51,15 +54,15 @@ Upgrading in a nutshell #. Request an upgraded test database (see :ref:`obtaining an upgraded test database `). +#. (If applicable) : upgrade the source code of your custom module to be compatible with the new + version of Odoo (see :ref:`upgrading custom modules `). + #. Thoroughly test the upgraded database (see :ref:`testing the new version of the database `). #. Report any issue encountered during the testing to Odoo via the `support page `__. -#. (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 +72,6 @@ Upgrading in a nutshell #. Report any issue encountered during the upgrade to Odoo via the `support page `__. -.. TODOUPG: Once the page for developers is published, put this at 4) -.. (see :ref:`upgrading customizations `). - .. _upgrade/request-test-database: Obtaining an upgraded test database diff --git a/content/developer/howtos.rst b/content/developer/howtos.rst index 8f60f60632..b1a83072a2 100644 --- a/content/developer/howtos.rst +++ b/content/developer/howtos.rst @@ -20,7 +20,7 @@ How-to guides howtos/translations howtos/website_themes howtos/connect_device - howtos/upgrade_module + howtos/upgrade_modules .. cards:: @@ -86,7 +86,7 @@ How-to guides Learn how to enable a module to detect and communicate with an IoT device. - .. card:: Upgrade a custom module - :target: howtos/upgrade_module + .. card:: Upgrading custom modules + :target: howtos/upgrade_modules Learn how to upgrade a custom module to a new version of Odoo. \ No newline at end of file diff --git a/content/developer/howtos/upgrade_module.rst b/content/developer/howtos/upgrade_modules.rst similarity index 100% rename from content/developer/howtos/upgrade_module.rst rename to content/developer/howtos/upgrade_modules.rst From a21269ad329c9139c5237581e9f7106d3523e57c Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 09:03:18 +0100 Subject: [PATCH 04/12] [IMP] upgrade technical documentation: move to howtos --- content/administration/upgrade.rst | 8 +- content/developer/howtos.rst | 8 +- .../howtos/upgrade/migration_scripts.rst | 1 + ...tions.rst => upgrading_custom_modules.rst} | 49 ++-- .../howtos/upgrade/upgrading_data.rst | 80 ++++++ .../upgrading_studio_customizations.rst | 103 ++++++++ content/developer/howtos/upgrade_modules.rst | 228 ------------------ .../howtos/upgrading_customized_database.rst | 53 ++++ content/developer/reference.rst | 1 - 9 files changed, 268 insertions(+), 263 deletions(-) rename content/developer/howtos/upgrade/{upgrading_customizations.rst => upgrading_custom_modules.rst} (75%) create mode 100644 content/developer/howtos/upgrade/upgrading_data.rst create mode 100644 content/developer/howtos/upgrade/upgrading_studio_customizations.rst delete mode 100644 content/developer/howtos/upgrade_modules.rst create mode 100644 content/developer/howtos/upgrading_customized_database.rst diff --git a/content/administration/upgrade.rst b/content/administration/upgrade.rst index 31c6ea6879..5b23b4e6da 100644 --- a/content/administration/upgrade.rst +++ b/content/administration/upgrade.rst @@ -42,8 +42,8 @@ An upgrade does not cover: 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 - ` while also :ref:`upgrading the source code of your custom - modules `. + ` while also :doc:`upgrading the source code of your custom + modules `. .. TODOUPG : once the page for developers is published, uncomment and link .. :doc:`first upgrade its source code ` @@ -54,8 +54,8 @@ Upgrading in a nutshell #. Request an upgraded test database (see :ref:`obtaining an upgraded test database `). -#. (If applicable) : upgrade the source code of your custom module to be compatible with the new - version of Odoo (see :ref:`upgrading custom modules `). +#. If applicable : upgrade the source code of your custom module to be compatible with the new + version of Odoo (see :doc:`/developer/howtos/upgrading_customized_database`). #. Thoroughly test the upgraded database (see :ref:`testing the new version of the database `). diff --git a/content/developer/howtos.rst b/content/developer/howtos.rst index b1a83072a2..44a10cc354 100644 --- a/content/developer/howtos.rst +++ b/content/developer/howtos.rst @@ -20,7 +20,7 @@ How-to guides howtos/translations howtos/website_themes howtos/connect_device - howtos/upgrade_modules + howtos/upgrading_customized_database .. cards:: @@ -86,7 +86,7 @@ How-to guides Learn how to enable a module to detect and communicate with an IoT device. - .. card:: Upgrading custom modules - :target: howtos/upgrade_modules + .. card:: Upgrading a customized database + :target: howtos/upgrading_customized_database - Learn how to upgrade a custom module to a new version of Odoo. \ No newline at end of file + Learn how to upgrade a customized database, as well as the code and data of its custom modules. \ No newline at end of file diff --git a/content/developer/howtos/upgrade/migration_scripts.rst b/content/developer/howtos/upgrade/migration_scripts.rst index 38b45cfc31..c34c288ce3 100644 --- a/content/developer/howtos/upgrade/migration_scripts.rst +++ b/content/developer/howtos/upgrade/migration_scripts.rst @@ -1,3 +1,4 @@ +.. _upgrade/migration-scripts: ================= Migration scripts diff --git a/content/developer/howtos/upgrade/upgrading_customizations.rst b/content/developer/howtos/upgrade/upgrading_custom_modules.rst similarity index 75% rename from content/developer/howtos/upgrade/upgrading_customizations.rst rename to content/developer/howtos/upgrade/upgrading_custom_modules.rst index 374c212c2b..32fae0ae30 100644 --- a/content/developer/howtos/upgrade/upgrading_customizations.rst +++ b/content/developer/howtos/upgrade/upgrading_custom_modules.rst @@ -1,53 +1,50 @@ - ======================== -Upgrading customizations +Upgrading custom modules ======================== -The source code of custom modules maintained by third parties must be upgraded to be compatible with -each new version of Odoo. This usually requires a static analysis of the code to find all the -references of deprecated elements. However, it can also be done by installing the module and fixing -the errors that occur during the installation. +Custom modules are usually not compatible out of the box with a new version of Odoo due to changes +in the standard modules, such as models being merged, fields being renamed, or methods being +refactored. Therefore, a new version of the modules must be created for each new version +of Odoo, in which its source code is adapted to the new version. + +To make the process of releasing a new version easier, we recommend exploring the new features +brought by the latest versions of Odoo to find out if any of your customizations have become +derprecated or can be replaced by a standard feature. + +.. example:: + In Odoo 15, the `sale.subscription` model has been merged into the `sale.order` module. Therefore, + any field added to the `sale.subscription` model must be ported over to the `sale.order` model. + Other references such as related fields, views, reports, etc., must also be updated to match the + new model name. Information on the changes between versions can be found in the `release notes `_ and the :ref:`upgrade report `. .. seealso:: - - :ref:`reference/views` + - :doc:`/developer/reference/user_interface/view_records` - :ref:`reference/fields` - :ref:`reference/orm/models` -.. _upgrade/comparing_customizations: - -Comparing customizations to the new version -------------------------------------------- - -As many new features are added with each new version, some customizations may become obsolete when -equivalent features become part of the standard version of Odoo. - -Therefore, exploring the new features and comparing them with your customizations is recommended. -Removing unnecessary customizations reduces the work needed to maintain and upgrade your database. - .. _upgrade/remove_customizations: Removing customizations ----------------------- Customizations that have become redundant with the release of a new version of Odoo can be removed -from your database with a :ref:`migration script ` using the +from your database with a :ref:`migration script ` using the `uninstall_module` method from the `upgrade-util package `__. -This method renames the field and the column in the database but does not impact views, reports, -filters, mail templates, automated and server actions, etc., that refer to those fields. Those -references must be found and removed from the database, as well as in the same migration script. + +.. warning:: + `uninstall_module` renames the field and the column in the database but does not impact views, reports, + filters, mail templates, automated and server actions, etc., that refer to those fields. Those + references must be found and removed from the database, preferably in the same migration script. .. important:: :ref:`Testing your database ` is crucial, especially when uninstalling a custom module. Any customized view, report, filter, mail template, automated and server actions, - etc., referring to an uninstall field will prevent them from working correctly and might block + etc., referring to an uninstalled field will prevent them from working correctly and might block your processes in certain situations. -.. seealso:: - :ref:`upgrade/comparing_customizations` - Upgrading custom fields and their data -------------------------------------- diff --git a/content/developer/howtos/upgrade/upgrading_data.rst b/content/developer/howtos/upgrade/upgrading_data.rst new file mode 100644 index 0000000000..3ed6f152c5 --- /dev/null +++ b/content/developer/howtos/upgrade/upgrading_data.rst @@ -0,0 +1,80 @@ +============== +Upgrading data +============== + +Errors during upgrade +--------------------- + +Suppose some critical data is removed during the standard upgrade process or an exception is raised, +stopping the upgrade process. In that case, a migration script must be injected during the process +to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the +Upgrade server, and custom migration scripts are only executed after the standard process succeeds. + +Errors can be due to two things: + + - An inconsistency in the data of the original database, in which case the underlying issue can be + fixed in production **after testing on a duplicated database** + - An error during the generation of data during the upgrade, in which case the `intervention of a + developer of the Upgrade team `_ is required to fix the issue and + restart the upgrade process + +.. spoiler:: Access error + + Access errors are raised when a user tries to access a record without the proper access rights. + During upgrades, the administrator user (`ID=2`) is used to perform all operations and, + therefore, should be able to access all records. + + .. example:: + `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) + records.` + + This message means the administrator (`ID=2`) does not have the access rights to read a + record of the model `hr.applicant` (Recruitment app). The same error message can appear when + trying to access a record from the web interface without the access rights to do so. + + The error can be solved by giving back all administrator access rights to the administrator, + even for custom groups or record rules. + +.. spoiler:: Validation error + + Validation errors are raised by various safeguards implemented in the source code of Odoo, + ensuring data is consistent. The message is usually accompanied by the traceback, which might + display which record is causing the error. + + .. example:: + `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax + using it.` + + This error is raised in `this part of the code `_. + It is possible to conclude that this error appears if there is a record of the `account.tax` + model for which the country set on the tax group differs from the country set on the tax + itself. + + Therefore, fixing the error requires searching for faulty taxes and fixing them by setting + their country to the country of their tax group (or vice versa), either manually via the web + page of the database, with PSQL queries, or with the :ref:`Odoo shell + `, depending on the hosting type. + +.. seealso:: + - :ref:`reference/exceptions` + - :doc:`Data access restriction ` + - :doc:`Access rights ` + - :doc:`User management ` + +Upgrading server, scheduled, and automated actions +-------------------------------------------------- + +References to fields in server, scheduled, and automated actions might be broken due to changes in +the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a +new Record*, or *Update the Record*. + +Those actions are susceptible to being removed by the standard upgrade process, requiring +`intervention from an Odoo developer `_. Otherwise, it can be fixed +with a custom `migration script `_. + +.. note:: + To prevent actions from being removed, it is possible to preemptively change the reference(s) to + a field before upgrading and restoring them after the upgrade process. + +.. seealso:: + :ref:`Server actions ` \ No newline at end of file diff --git a/content/developer/howtos/upgrade/upgrading_studio_customizations.rst b/content/developer/howtos/upgrade/upgrading_studio_customizations.rst new file mode 100644 index 0000000000..d242cbefbc --- /dev/null +++ b/content/developer/howtos/upgrade/upgrading_studio_customizations.rst @@ -0,0 +1,103 @@ +=============================== +Upgrading studio customizations +=============================== + +TODOUPG should we publish upgrading studio customizations even though it will always be handled +by Odoo ? Given the time it takes some customers would be very happy to be able to fix it +themselves, especially since it can be fixed in the custom module mig script + +.. _reference/upgrade/studio_views: + +Studio views +------------ + +The upgrade process archives Odoo Studio view customizations if an issue is detected with their +definition. The logs will display a warning, but the upgrade process will not halt. + +Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` +attribute) and show the complete error message, allowing you to find the broken Xpath expression. It +is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. + +Views can also be deleted from the database during the upgrade if their corresponding model becomes +invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after +the standard upgrade process, but their deletion can be prevented by `requesting assistance from a +developer of the Upgrade team `_. + +.. note:: + Custom views generated by Studio do not always contain immutable targets in their Xpath + definition. When developing custom views with Studio, changing the generated Xpath to improve + their robustness is a good practice. + +.. spoiler:: The custom view caused validation issues + + This warning is raised when a custom view created with Studio is not valid anymore due to Xpath + targets that cannot be found in the parent view. + + .. example:: + + .. code-block:: console + + 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view + + View name: Odoo Studio: crm.lead.tree.opportunity customization + Error context: + view: ir.ui.view(1137,) + xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 + view.model: crm.lead + view.parent: ir.ui.view(902,) + + 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. + Disabling it for the migration ... + + This issue can be fixed by changing the Xpath target (the `expr` attribute) with a + :ref:`migration script ` using the `edit_view` method from + the `upgrade-util package `_ to match the same element in + the new version of the view. + +.. seealso:: + - :ref:`reference/exceptions` + - :doc:`/developer/reference/user_interface/view_records` + - :ref:`Inheritance ` + +Studio fields +------------- + +In case of invalid references on a field created by Studio, such as the `model`, `related`, or +`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be +accessible for the custom migration scripts or on the upgraded database. + +This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be +recoverable once the upgrade of the production database is completed. + +.. example:: + In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with + `account.move` and was then subsequently removed. The standard migration scripts took care of + moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the + columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not + automatically moved. Once the data migration to `account_move` was completed, the + `account_invoice` table was dropped, with all the custom data still in it. + +In those situations, you can `request assistance from Odoo `_ to upgrade +your custom fields during the standard upgrade process by specifying the following: + +- The name of the field(s) removed from your database +- The name of the model(s) they were on +- The reason why they were removed (model removed, relation removed, related field removed, etc.) +- Which new model, relation, or related field they should be on +- Any additional information that could help retrieve the fields + +Studio reports +-------------- + +The mechanism behind reports customization generated by Studio is the same as the one used for +:ref:`reference/upgrade/studio_views`. + +For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, +meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying +the content of the upgraded report and writing it over the content of the duplicated report. Note +that this might lead to issues with the Studio customizations made on the duplicate, such as +invalid Xpath targets. + +.. important:: + The code of a duplicated report should not be modified to ensure it is upgradable. If you need + to modify the code of a report, it is recommended to customize it with Studio. \ No newline at end of file diff --git a/content/developer/howtos/upgrade_modules.rst b/content/developer/howtos/upgrade_modules.rst deleted file mode 100644 index 0bed26e3c7..0000000000 --- a/content/developer/howtos/upgrade_modules.rst +++ /dev/null @@ -1,228 +0,0 @@ -:show-content: -:hide-page-toc: -:show-toc: - -====================== -Upgrade for developers -====================== - -.. note:: - This page is intended to explain the technical aspects of Upgrading. For a more - general overview, please refer to the :ref:`upgrade documentation `. - -For a custom module to be used in a database running the new version of Odoo, a new version of its -source code be compatible with the latest changes in the source code of Odoo must bereleased. -Those changes usually include fields, models, methods, or views being renamed or refactored. - -Renaming references might not be enough, as the :ref:`ORM ` would not be able to -differenciate a field being deleted and another being created, from a simple renaming of a field. -Therefore, you might have to write :ref:`custom migration scripts ` -to reflect certain changes in the source code of your custom modules to their corresponding data. - -For the standard modules of Odoo, the new version of its source code, with their migration -scripts, are published by Odoo alongside the release of the new version, while for custom modules, -the new version with its migration scripts must be developed by the maintainer of the module. - -.. important:: - When committing to upgrading custom modules, it is crucial to halt the development of new - features since they would have to be upgraded as well, and might create new issues during the - upgrade process. Once the new version of your module has been released, you may resume the - development. - -.. seealso:: - `Upgrade-util package `_ - -In a nutshell, upgrading your customizations consists of: - -#. Halting the development of new customizations -#. Requesting an upgraded database and upgrading the custom modules' source code -#. Testing the upgraded modules on a new database, to catch any issue with the code -#. Testing the upgraded database with the new version of its modules, to catch any issue with the - data - -.. toctree:: - :maxdepth: 2 - - upgrade/migration_scripts - upgrade/upgrading_customizations - -TODO : bottom of this page moved to its own how to page - -Upgrading data -============== - -Errors during upgrade ---------------------- - -Suppose some critical data is removed during the standard upgrade process or an exception is raised, -stopping the upgrade process. In that case, a migration script must be injected during the process -to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the -Upgrade server, and custom migration scripts are only executed after the standard process succeeds. - -Errors can be due to two things: - - - An inconsistency in the data of the original database, in which case the underlying issue can be - fixed in production **after testing on a duplicated database** - - An error during the generation of data during the upgrade, in which case the `intervention of a - developer of the Upgrade team `_ is required to fix the issue and - restart the upgrade process - -.. spoiler:: Access error - - Access errors are raised when a user tries to access a record without the proper access rights. - During upgrades, the administrator user (`ID=2`) is used to perform all operations and, - therefore, should be able to access all records. - - .. example:: - `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) - records.` - - This message means the administrator (`ID=2`) does not have the access rights to read a - record of the model `hr.applicant` (Recruitment app). The same error message can appear when - trying to access a record from the web interface without the access rights to do so. - - The error can be solved by giving back all administrator access rights to the administrator, - even for custom groups or record rules. - -.. spoiler:: Validation error - - Validation errors are raised by various safeguards implemented in the source code of Odoo, - ensuring data is consistent. The message is usually accompanied by the traceback, which might - display which record is causing the error. - - .. example:: - `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax - using it.` - - This error is raised in `this part of the code `_. - It is possible to conclude that this error appears if there is a record of the `account.tax` - model for which the country set on the tax group differs from the country set on the tax - itself. - - Therefore, fixing the error requires searching for faulty taxes and fixing them by setting - their country to the country of their tax group (or vice versa), either manually via the web - page of the database, with PSQL queries, or with the :ref:`Odoo shell - `, depending on the hosting type. - -.. seealso:: - - :ref:`reference/exceptions` - - :doc:`Data access restriction <../tutorials/restrict_data_access>` - - :doc:`Access rights <../../applications/general/users/access_rights>` - - :doc:`User management <../../applications/general/users/manage_users>` - -Upgrading server, scheduled, and automated actions --------------------------------------------------- - -References to fields in server, scheduled, and automated actions might be broken due to changes in -the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a -new Record*, or *Update the Record*. - -Those actions are susceptible to being removed by the standard upgrade process, requiring -`intervention from an Odoo developer `_. Otherwise, it can be fixed -with a custom `migration script `_. - -.. note:: - To prevent actions from being removed, it is possible to preemptively change the reference(s) to - a field before upgrading and restoring them after the upgrade process. - -.. seealso:: - :ref:`Server actions ` - -Upgrading studio customizations -=============================== - -.. _reference/upgrade/studio_views: - -Studio views ------------- - -The upgrade process archives Odoo Studio view customizations if an issue is detected with their -definition. The logs will display a warning, but the upgrade process will not halt. - -Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` -attribute) and show the complete error message, allowing you to find the broken Xpath expression. It -is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. - -Views can also be deleted from the database during the upgrade if their corresponding model becomes -invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after -the standard upgrade process, but their deletion can be prevented by `requesting assistance from a -developer of the Upgrade team `_. - -.. note:: - Custom views generated by Studio do not always contain immutable targets in their Xpath - definition. When developing custom views with Studio, changing the generated Xpath to improve - their robustness is a good practice. - -.. spoiler:: The custom view caused validation issues - - This warning is raised when a custom view created with Studio is not valid anymore due to Xpath - targets that cannot be found in the parent view. - - .. example:: - - .. code-block:: console - - 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view - - View name: Odoo Studio: crm.lead.tree.opportunity customization - Error context: - view: ir.ui.view(1137,) - xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 - view.model: crm.lead - view.parent: ir.ui.view(902,) - - 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. - Disabling it for the migration ... - - This issue can be fixed by changing the Xpath target (the `expr` attribute) with a - :ref:`migration script ` using the `edit_view` method from - the `upgrade-util package `_ to match the same element in - the new version of the view. - -.. seealso:: - - :ref:`reference/exceptions` - - :ref:`reference/views` - - :ref:`reference/views/inheritance` - -Studio fields -------------- - -In case of invalid references on a field created by Studio, such as the `model`, `related`, or -`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be -accessible for the custom migration scripts or on the upgraded database. - -This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be -recoverable once the upgrade of the production database is completed. - -.. example:: - In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with - `account.move` and was then subsequently removed. The standard migration scripts took care of - moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the - columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not - automatically moved. Once the data migration to `account_move` was completed, the - `account_invoice` table was dropped, with all the custom data still in it. - -In those situations, you can `request assistance from Odoo `_ to upgrade -your custom fields during the standard upgrade process by specifying the following: - -- The name of the field(s) removed from your database -- The name of the model(s) they were on -- The reason why they were removed (model removed, relation removed, related field removed, etc.) -- Which new model, relation, or related field they should be on -- Any additional information that could help retrieve the fields - -Studio reports --------------- - -The mechanism behind reports customization generated by Studio is the same as the one used for -:ref:`reference/upgrade/studio_views`. - -For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, -meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying -the content of the upgraded report and writing it over the content of the duplicated report. Note -that this might lead to issues with the Studio customizations made on the duplicate, such as -invalid Xpath targets. - -.. important:: - The code of a duplicated report should not be modified to ensure it is upgradable. If you need - to modify the code of a report, it is recommended to customize it with Studio. \ No newline at end of file diff --git a/content/developer/howtos/upgrading_customized_database.rst b/content/developer/howtos/upgrading_customized_database.rst new file mode 100644 index 0000000000..6e43d8cdaa --- /dev/null +++ b/content/developer/howtos/upgrading_customized_database.rst @@ -0,0 +1,53 @@ +:show-content: +:hide-page-toc: +:show-toc: + +=============================== +Upgrading a customized database +=============================== + +.. note:: + This page is intended to explain the technical aspects of Upgrading. For a more + general overview, please refer to the :ref:`upgrade documentation `. + +Upgrading a database that contains custom modules requires additional steps compared to +databases running the standard modules of Odoo since the source code of the custom modules +must be upgraded as well. + +For a custom module to be used in a database running the new version of Odoo, a new version of its +source code be compatible with the latest changes in the source code of Odoo must bereleased. +Those changes usually include fields, models, methods, or views being renamed or refactored. + +Renaming references might not be enough, as the :ref:`ORM ` would not be able to +differenciate a field being deleted and another being created, from a simple renaming of a field. +Therefore, you might have to write :ref:`custom migration scripts ` +to reflect certain changes in the source code of your custom modules to their corresponding data. + +For the standard modules of Odoo, the new version of its source code, with their migration +scripts, are published by Odoo alongside the release of the new version, while for custom modules, +the new version with its migration scripts must be developed by the maintainer of the module. + +.. important:: + When committing to upgrading custom modules, it is crucial to halt the development of new + features since they would have to be upgraded as well, and might create new issues during the + upgrade process. Once the new version of your module has been released, you may resume the + development. + +.. seealso:: + `Upgrade-util package `_ + +In a nutshell, upgrading your customized database requires the following steps: + +#. Halting the development of new customizations +#. Requesting an upgraded database and upgrading the custom modules' source code +#. Testing the upgraded modules on a new database, to catch any issue with the code +#. Testing the upgraded database with the new version of its modules, to catch any issue with the + data + +.. toctree:: + :maxdepth: 2 + + upgrade/migration_scripts + upgrade/upgrading_custom_modules + upgrade/upgrading_data + upgrade/upgrading_studio_customizations \ No newline at end of file diff --git a/content/developer/reference.rst b/content/developer/reference.rst index 4e53b3cce7..96ab9eb529 100644 --- a/content/developer/reference.rst +++ b/content/developer/reference.rst @@ -14,4 +14,3 @@ Reference reference/cli reference/external_api reference/extract_api - reference/upgrade From ae210449c954ab42a2df79ee270c90c5b2ccd331 Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 09:28:42 +0100 Subject: [PATCH 05/12] [IMP] upgrade technical documentation : add questions --- .../developer/howtos/upgrade/migration_scripts.rst | 12 ++++++++++++ .../howtos/upgrade/upgrading_custom_modules.rst | 7 +++++++ content/developer/howtos/upgrade/upgrading_data.rst | 5 +++++ .../howtos/upgrading_customized_database.rst | 2 +- 4 files changed, 25 insertions(+), 1 deletion(-) diff --git a/content/developer/howtos/upgrade/migration_scripts.rst b/content/developer/howtos/upgrade/migration_scripts.rst index c34c288ce3..be33ab369f 100644 --- a/content/developer/howtos/upgrade/migration_scripts.rst +++ b/content/developer/howtos/upgrade/migration_scripts.rst @@ -4,6 +4,18 @@ Migration scripts ================= +TODOUPG this page should be about migration scripts : +#. What they are (python scripts that receives the psql cursor and the version) +#. What they are for : applying a modification on the data of your database when upgrading a module +#. In what circumstances you should use them : when changing the source code of your module between +2 versions of Odoo +#. How to write them : examples, upgrade-util package +#. The different phases and what is their impact: pre no ORM, before module is loaded so before +your new field gets created +#. Where to put them : in /migration**s** +#. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your +dump, run it and upgrade all modules via starting odoo-bin + A migration script is a Python file containing a function called `migrate`, which the upgrade process invokes at the appropriate time. Typically, this function executes one or multiple SQL queries and can also access Odoo's ORM, as well as the `upgrade-util package diff --git a/content/developer/howtos/upgrade/upgrading_custom_modules.rst b/content/developer/howtos/upgrade/upgrading_custom_modules.rst index 32fae0ae30..2773c97f96 100644 --- a/content/developer/howtos/upgrade/upgrading_custom_modules.rst +++ b/content/developer/howtos/upgrade/upgrading_custom_modules.rst @@ -2,6 +2,13 @@ Upgrading custom modules ======================== +TODOUPG this page should be about upgrading custom modules: +#. Why they are not compatible out of the box +#. The process of developing a new version of a custom module : make it installable on empty db, +upgrade a database using it to test the migration of data +#. How to find the derprecated elements +#. Don't forget to write migration scripts + Custom modules are usually not compatible out of the box with a new version of Odoo due to changes in the standard modules, such as models being merged, fields being renamed, or methods being refactored. Therefore, a new version of the modules must be created for each new version diff --git a/content/developer/howtos/upgrade/upgrading_data.rst b/content/developer/howtos/upgrade/upgrading_data.rst index 3ed6f152c5..9d3245f202 100644 --- a/content/developer/howtos/upgrade/upgrading_data.rst +++ b/content/developer/howtos/upgrade/upgrading_data.rst @@ -2,6 +2,11 @@ Upgrading data ============== +TODOUPG this page should be about upgrading data : +but should we publish this ? Since Odoo always takes care of it. Even though it can be fixed +in custom mig script after restoring + + Errors during upgrade --------------------- diff --git a/content/developer/howtos/upgrading_customized_database.rst b/content/developer/howtos/upgrading_customized_database.rst index 6e43d8cdaa..2dde849b35 100644 --- a/content/developer/howtos/upgrading_customized_database.rst +++ b/content/developer/howtos/upgrading_customized_database.rst @@ -8,7 +8,7 @@ Upgrading a customized database .. note:: This page is intended to explain the technical aspects of Upgrading. For a more - general overview, please refer to the :ref:`upgrade documentation `. + general overview, please refer to the :doc:`upgrade documentation `. Upgrading a database that contains custom modules requires additional steps compared to databases running the standard modules of Odoo since the source code of the custom modules From ae086fc519516a63256ecde952906607f1d400ad Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 12:46:48 +0100 Subject: [PATCH 06/12] [IMP] upgrade technical doc. move all to one page --- content/administration/upgrade.rst | 30 +- content/developer/howtos.rst | 4 +- .../upgrade/upgrading_custom_modules.rst | 108 ------ .../howtos/upgrade/upgrading_data.rst | 85 ----- .../upgrading_studio_customizations.rst | 103 ------ .../developer/howtos/upgrade_custom_db.rst | 334 ++++++++++++++++++ .../howtos/upgrading_customized_database.rst | 53 --- 7 files changed, 356 insertions(+), 361 deletions(-) delete mode 100644 content/developer/howtos/upgrade/upgrading_custom_modules.rst delete mode 100644 content/developer/howtos/upgrade/upgrading_data.rst delete mode 100644 content/developer/howtos/upgrade/upgrading_studio_customizations.rst create mode 100644 content/developer/howtos/upgrade_custom_db.rst delete mode 100644 content/developer/howtos/upgrading_customized_database.rst diff --git a/content/administration/upgrade.rst b/content/administration/upgrade.rst index 5b23b4e6da..eac8f33ab0 100644 --- a/content/administration/upgrade.rst +++ b/content/administration/upgrade.rst @@ -43,7 +43,7 @@ An upgrade does not cover: 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 ` while also :doc:`upgrading the source code of your custom - modules `. + modules `. .. TODOUPG : once the page for developers is published, uncomment and link .. :doc:`first upgrade its source code ` @@ -55,7 +55,7 @@ Upgrading in a nutshell `). #. If applicable : upgrade the source code of your custom module to be compatible with the new - version of Odoo (see :doc:`/developer/howtos/upgrading_customized_database`). + version of Odoo (see :doc:`/developer/howtos/upgrade_custom_db`). #. Thoroughly test the upgraded database (see :ref:`testing the new version of the database `). @@ -136,18 +136,17 @@ project `_. file of the upgrade process can be found in your newly upgraded staging build by going to :file:`~/logs/upgrade.log`. - .. note:: + .. 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 ` for more information. In - .. addition, if a module is not needed after an upgrade, :ref:`you can - .. remove customizations `. + Check out the :ref:`upgrade for developers' + documentation ` for more information. In + addition, if a module is not needed after an upgrade, :ref:`you can + remove customizations `. .. group-tab:: On-premise @@ -167,6 +166,18 @@ project `_. An upgraded test database can also be requested via the `Upgrade page `_. + .. 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. + + Check out the :ref:`upgrade for developers' + documentation ` for more information. In + addition, if a module is not needed after an upgrade, :ref:`you can + remove customizations `. + .. 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 @@ -338,8 +349,7 @@ 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 `. + More information on how to upgrade your custom modules can be found in the :doc:``. .. group-tab:: On-premise diff --git a/content/developer/howtos.rst b/content/developer/howtos.rst index 44a10cc354..df40ded8b7 100644 --- a/content/developer/howtos.rst +++ b/content/developer/howtos.rst @@ -20,7 +20,7 @@ How-to guides howtos/translations howtos/website_themes howtos/connect_device - howtos/upgrading_customized_database + howtos/upgrade_custom_db .. cards:: @@ -87,6 +87,6 @@ How-to guides Learn how to enable a module to detect and communicate with an IoT device. .. card:: Upgrading a customized database - :target: howtos/upgrading_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. \ No newline at end of file diff --git a/content/developer/howtos/upgrade/upgrading_custom_modules.rst b/content/developer/howtos/upgrade/upgrading_custom_modules.rst deleted file mode 100644 index 2773c97f96..0000000000 --- a/content/developer/howtos/upgrade/upgrading_custom_modules.rst +++ /dev/null @@ -1,108 +0,0 @@ -======================== -Upgrading custom modules -======================== - -TODOUPG this page should be about upgrading custom modules: -#. Why they are not compatible out of the box -#. The process of developing a new version of a custom module : make it installable on empty db, -upgrade a database using it to test the migration of data -#. How to find the derprecated elements -#. Don't forget to write migration scripts - -Custom modules are usually not compatible out of the box with a new version of Odoo due to changes -in the standard modules, such as models being merged, fields being renamed, or methods being -refactored. Therefore, a new version of the modules must be created for each new version -of Odoo, in which its source code is adapted to the new version. - -To make the process of releasing a new version easier, we recommend exploring the new features -brought by the latest versions of Odoo to find out if any of your customizations have become -derprecated or can be replaced by a standard feature. - -.. example:: - In Odoo 15, the `sale.subscription` model has been merged into the `sale.order` module. Therefore, - any field added to the `sale.subscription` model must be ported over to the `sale.order` model. - Other references such as related fields, views, reports, etc., must also be updated to match the - new model name. - -Information on the changes between versions can be found in the `release notes -`_ and the :ref:`upgrade report `. - -.. seealso:: - - :doc:`/developer/reference/user_interface/view_records` - - :ref:`reference/fields` - - :ref:`reference/orm/models` - -.. _upgrade/remove_customizations: - -Removing customizations ------------------------ - -Customizations that have become redundant with the release of a new version of Odoo can be removed -from your database with a :ref:`migration script ` using the -`uninstall_module` method from the `upgrade-util package `__. - -.. warning:: - `uninstall_module` renames the field and the column in the database but does not impact views, reports, - filters, mail templates, automated and server actions, etc., that refer to those fields. Those - references must be found and removed from the database, preferably in the same migration script. - -.. important:: - :ref:`Testing your database ` is crucial, especially when uninstalling a - custom module. Any customized view, report, filter, mail template, automated and server actions, - etc., referring to an uninstalled field will prevent them from working correctly and might block - your processes in certain situations. - -Upgrading custom fields and their data --------------------------------------- - -Any custom field that has a reference to a modified standard field must be adapted to the new -version of Odoo. To find the corresponding field in the new version, we recommend looking at its -properties and finding a field with matching properties. You can also use the :ref:`upgrade report -` and the `release notes `_ to support -your search. - -.. example:: - In Odoo 12 and before, the `account.invoice` model had a field named `refund_invoice_id` (`source - code `_), - which is absent on the `account.move` model after Odoo 13. This field was renamed to - `reversed_entry_id` during the upgrade process. It is possible to find this information by - searching for another Many2one field in `account.move` related to `account.move`, for example, - `in Odoo 16 `_. - -.. note:: - Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. - However, this only renames the field and column names. Therefore, custom views, reports, field - relations, automated actions, etc., might still refer to the old field name and need to be - updated in the migration script as well. - -Upgrading models and methods definitions ----------------------------------------- - -Upgrading custom models consists mainly of ensuring that the module name and its inheritances -are correct. The :ref:`upgrade report ` and the `release notes -`_ can contain helpful information concerning various standard -models being changed or renamed. - -.. example:: - The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 `_ - that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 `_. - -If a custom model overrides standard methods, you must ensure that their name still matches the -name of the method they are overriding. In case of changes, you can search the method's source code -in the new version to find its new name. If the method has been refactored, the source code might -not exactly match, and a manual search is then required. - -Upgrading views definitions ---------------------------- - -Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's -`` tag, which can happen during a module update or when rendering it. - -Most of the time, the incompatibility of a custom view is expressed via an error when parsing the -view, which can happen during the update of a module or when rendering it. - -Custom views for custom models only require upgrading if the custom model has been changed. In -contrast, custom views inheriting from standard views can be impacted by changes in the standard -views. In this case, the custom views' source code requires an upgrade to be compatible with the new -version of its parent view. This can be done by retargetting the various Xpath expressions to match -an equivalent element that might have been moved or renamed. \ No newline at end of file diff --git a/content/developer/howtos/upgrade/upgrading_data.rst b/content/developer/howtos/upgrade/upgrading_data.rst deleted file mode 100644 index 9d3245f202..0000000000 --- a/content/developer/howtos/upgrade/upgrading_data.rst +++ /dev/null @@ -1,85 +0,0 @@ -============== -Upgrading data -============== - -TODOUPG this page should be about upgrading data : -but should we publish this ? Since Odoo always takes care of it. Even though it can be fixed -in custom mig script after restoring - - -Errors during upgrade ---------------------- - -Suppose some critical data is removed during the standard upgrade process or an exception is raised, -stopping the upgrade process. In that case, a migration script must be injected during the process -to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the -Upgrade server, and custom migration scripts are only executed after the standard process succeeds. - -Errors can be due to two things: - - - An inconsistency in the data of the original database, in which case the underlying issue can be - fixed in production **after testing on a duplicated database** - - An error during the generation of data during the upgrade, in which case the `intervention of a - developer of the Upgrade team `_ is required to fix the issue and - restart the upgrade process - -.. spoiler:: Access error - - Access errors are raised when a user tries to access a record without the proper access rights. - During upgrades, the administrator user (`ID=2`) is used to perform all operations and, - therefore, should be able to access all records. - - .. example:: - `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) - records.` - - This message means the administrator (`ID=2`) does not have the access rights to read a - record of the model `hr.applicant` (Recruitment app). The same error message can appear when - trying to access a record from the web interface without the access rights to do so. - - The error can be solved by giving back all administrator access rights to the administrator, - even for custom groups or record rules. - -.. spoiler:: Validation error - - Validation errors are raised by various safeguards implemented in the source code of Odoo, - ensuring data is consistent. The message is usually accompanied by the traceback, which might - display which record is causing the error. - - .. example:: - `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax - using it.` - - This error is raised in `this part of the code `_. - It is possible to conclude that this error appears if there is a record of the `account.tax` - model for which the country set on the tax group differs from the country set on the tax - itself. - - Therefore, fixing the error requires searching for faulty taxes and fixing them by setting - their country to the country of their tax group (or vice versa), either manually via the web - page of the database, with PSQL queries, or with the :ref:`Odoo shell - `, depending on the hosting type. - -.. seealso:: - - :ref:`reference/exceptions` - - :doc:`Data access restriction ` - - :doc:`Access rights ` - - :doc:`User management ` - -Upgrading server, scheduled, and automated actions --------------------------------------------------- - -References to fields in server, scheduled, and automated actions might be broken due to changes in -the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a -new Record*, or *Update the Record*. - -Those actions are susceptible to being removed by the standard upgrade process, requiring -`intervention from an Odoo developer `_. Otherwise, it can be fixed -with a custom `migration script `_. - -.. note:: - To prevent actions from being removed, it is possible to preemptively change the reference(s) to - a field before upgrading and restoring them after the upgrade process. - -.. seealso:: - :ref:`Server actions ` \ No newline at end of file diff --git a/content/developer/howtos/upgrade/upgrading_studio_customizations.rst b/content/developer/howtos/upgrade/upgrading_studio_customizations.rst deleted file mode 100644 index d242cbefbc..0000000000 --- a/content/developer/howtos/upgrade/upgrading_studio_customizations.rst +++ /dev/null @@ -1,103 +0,0 @@ -=============================== -Upgrading studio customizations -=============================== - -TODOUPG should we publish upgrading studio customizations even though it will always be handled -by Odoo ? Given the time it takes some customers would be very happy to be able to fix it -themselves, especially since it can be fixed in the custom module mig script - -.. _reference/upgrade/studio_views: - -Studio views ------------- - -The upgrade process archives Odoo Studio view customizations if an issue is detected with their -definition. The logs will display a warning, but the upgrade process will not halt. - -Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` -attribute) and show the complete error message, allowing you to find the broken Xpath expression. It -is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. - -Views can also be deleted from the database during the upgrade if their corresponding model becomes -invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after -the standard upgrade process, but their deletion can be prevented by `requesting assistance from a -developer of the Upgrade team `_. - -.. note:: - Custom views generated by Studio do not always contain immutable targets in their Xpath - definition. When developing custom views with Studio, changing the generated Xpath to improve - their robustness is a good practice. - -.. spoiler:: The custom view caused validation issues - - This warning is raised when a custom view created with Studio is not valid anymore due to Xpath - targets that cannot be found in the parent view. - - .. example:: - - .. code-block:: console - - 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view - - View name: Odoo Studio: crm.lead.tree.opportunity customization - Error context: - view: ir.ui.view(1137,) - xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 - view.model: crm.lead - view.parent: ir.ui.view(902,) - - 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. - Disabling it for the migration ... - - This issue can be fixed by changing the Xpath target (the `expr` attribute) with a - :ref:`migration script ` using the `edit_view` method from - the `upgrade-util package `_ to match the same element in - the new version of the view. - -.. seealso:: - - :ref:`reference/exceptions` - - :doc:`/developer/reference/user_interface/view_records` - - :ref:`Inheritance ` - -Studio fields -------------- - -In case of invalid references on a field created by Studio, such as the `model`, `related`, or -`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be -accessible for the custom migration scripts or on the upgraded database. - -This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be -recoverable once the upgrade of the production database is completed. - -.. example:: - In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with - `account.move` and was then subsequently removed. The standard migration scripts took care of - moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the - columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not - automatically moved. Once the data migration to `account_move` was completed, the - `account_invoice` table was dropped, with all the custom data still in it. - -In those situations, you can `request assistance from Odoo `_ to upgrade -your custom fields during the standard upgrade process by specifying the following: - -- The name of the field(s) removed from your database -- The name of the model(s) they were on -- The reason why they were removed (model removed, relation removed, related field removed, etc.) -- Which new model, relation, or related field they should be on -- Any additional information that could help retrieve the fields - -Studio reports --------------- - -The mechanism behind reports customization generated by Studio is the same as the one used for -:ref:`reference/upgrade/studio_views`. - -For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, -meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying -the content of the upgraded report and writing it over the content of the duplicated report. Note -that this might lead to issues with the Studio customizations made on the duplicate, such as -invalid Xpath targets. - -.. important:: - The code of a duplicated report should not be modified to ensure it is upgradable. If you need - to modify the code of a report, it is recommended to customize it with Studio. \ No newline at end of file diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst new file mode 100644 index 0000000000..71caaf382d --- /dev/null +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -0,0 +1,334 @@ +:show-content: +:hide-page-toc: +:show-toc: + +.. _upgrade/upgrade_custom_db: + +============================= +Upgrade a customized database +============================= + +.. note:: + This page is intended to explain the technical aspects of Upgrading. For a more + general overview, please refer to the :doc:`upgrade documentation `. + +Upgrading a database that contains custom modules requires additional steps compared to +databases running the standard modules of Odoo since the source code of the custom modules +must be upgraded as well. + +For a custom module to be used in a database running the new version of Odoo, a new version of its +source code be compatible with the latest changes in the source code of Odoo must bereleased. +Those changes usually include fields, models, methods, or views being renamed or refactored. + +Renaming references might not be enough, as the :ref:`ORM ` would not be able to +differenciate a field being deleted and another being created, from a simple renaming of a field. +Therefore, you might have to write :ref:`custom migration scripts ` +to reflect certain changes in the source code of your custom modules to their corresponding data. + +For the standard modules of Odoo, the new version of its source code, with their migration +scripts, are published by Odoo alongside the release of the new version, while for custom modules, +the new version with its migration scripts must be developed by the maintainer of the module. + +.. important:: + When committing to upgrading your custom database, it is crucial to halt the development of new + features since they would have to be upgraded as well, and might create new issues later during + the upgrade process. Once your upgrade is complete, you may resume their development. + +.. seealso:: + `Upgrade-util package `_ + +In a nutshell, upgrading your customized database requires the following steps: + +#. :ref:`Requesting an upgraded database ` and upgrading the +custom modules' source code +#. Testing the upgraded modules on a new database, to catch any issue with the code +#. Testing the upgraded database with the new version of its modules, to catch any issue with the + data +#. Upgrading the production database (see :ref:`upgrade/upgrade-prod`) + +Upgrading custom modules +======================== + +TODOUPG this page should be about upgrading custom modules: +#. Why they are not compatible out of the box +#. The process of developing a new version of a custom module : make it installable on empty db, +upgrade a database using it to test the migration of data +#. How to find the derprecated elements +#. Don't forget to write migration scripts + +Custom modules are usually not compatible out of the box with a new version of Odoo due to changes +in the standard modules, such as models being merged, fields being renamed, or methods being +refactored. Therefore, a new version of the modules must be created for each new version +of Odoo, in which its source code is adapted to the new version. + +To make the process of releasing a new version easier, we recommend exploring the new features +brought by the latest versions of Odoo to find out if any of your customizations have become +derprecated or can be replaced by a standard feature. + +.. example:: + In Odoo 15, the `sale.subscription` model has been merged into the `sale.order` module. Therefore, + any field added to the `sale.subscription` model must be ported over to the `sale.order` model. + Other references such as related fields, views, reports, etc., must also be updated to match the + new model name. + +Information on the changes between versions can be found in the `release notes +`_ and the :ref:`upgrade report `. + +.. seealso:: + - :doc:`/developer/reference/user_interface/view_records` + - :ref:`reference/fields` + - :ref:`reference/orm/models` + +.. _upgrade/remove_customizations: + +Removing customizations +----------------------- + +Modules that have become redundant with the release of a new version of Odoo can be removed +from your database with a :ref:`migration script ` using the +`uninstall_module` method from the `upgrade-util package `__. + +If only a few elements of a module have become redundant, it is possible to remove them one by one +using `remove_field`, `remove_model`, `remove_view`, etc., from the `upgrade-util package +__`. + +.. warning:: + Don't forget that fields, models, and views can still be referenced in other records such as + automated and server actions, mail templates, filters, etc. . Those references must be found + and removed from the database, preferably in the same migration script. + +.. important:: + :ref:`Testing your database ` is crucial, especially when removing + customizations. Any customized view, report, filter, mail template, automated and server + actions, etc., referring to a missing record will prevent them from working correctly and might + block your processes in certain situations. + +Upgrading custom fields and their data +-------------------------------------- + +Any custom field that has a reference to a modified standard field must be adapted to the new +version of Odoo. To find the corresponding field in the new version, we recommend looking at its +properties and finding a field with matching properties. You can also use the :ref:`upgrade report +` and the `release notes `_ to support +your search. + +.. example:: + In Odoo 12 and before, the `account.invoice` model had a field named `refund_invoice_id` (`source + code `_), + which is absent on the `account.move` model after Odoo 13. This field was renamed to + `reversed_entry_id` during the upgrade process. It is possible to find this information by + searching for another Many2one field in `account.move` related to `account.move`, for example, + `in Odoo 16 `_. + +.. note:: + Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. + However, this only renames the field and column names. Therefore, custom views, reports, field + relations, automated actions, etc., might still refer to the old field name and need to be + updated in the migration script as well. + +Upgrading models and methods definitions +---------------------------------------- + +Upgrading custom models consists mainly of ensuring that the module name and its inheritances +are correct. The :ref:`upgrade report ` and the `release notes +`_ can contain helpful information concerning various standard +models being changed or renamed. + +.. example:: + The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 + `_ + that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 + `_. + +If a custom model overrides standard methods, you must ensure that their name still matches the +name of the method they are overriding. In case of changes, you can search the method's source code +in the new version to find its new name. If the method has been refactored, the source code might +not exactly match, and a manual search is then required. + +Upgrading views definitions +--------------------------- + +Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's +`` tag, which can happen during a module update or when rendering it. + +Most of the time, the incompatibility of a custom view is expressed via an error when parsing the +view, which can happen during the update of a module or when rendering it. + +Custom views for custom models only require upgrading if the custom model has been changed. In +contrast, custom views inheriting from standard views can be impacted by changes in the standard +views. In this case, the custom views' source code requires an upgrade to be compatible with the new +version of its parent view. This can be done by retargetting the various Xpath expressions to match +an equivalent element that might have been moved or renamed. + +Testing the upgraded module +=========================== + +Once the source code of the custom modules has been upgraded, it is time to test them on a new +database to ensure that they does not depend on a previous installation (e.g., modules +already installed, data already present, etc.). This testing can help you detect issues with +your modules' dependencies, computed fields, etc. + +.. seealso:: + :ref:`Testing your database ` + +Upgrading data +============== + +Upgrading server, scheduled, and automated actions +-------------------------------------------------- + +References to fields in server, scheduled, and automated actions might be broken due to changes in +the fields' definitions. This is usually the case for the actions :guilabel:`Execute Python Code`, :guilabel:`Create a +new Record`, or :guilabel:`Update the Record`. + +TODOUPG: can they be removed, or will they simply be archived ? + +Those actions are susceptible to being removed by the standard upgrade process, requiring +`intervention from an Odoo developer `_. Otherwise, it can be fixed +with a custom `migration script `_. + +.. note:: + To prevent actions from being removed, it is possible to preemptively change the reference(s) to + a field before upgrading and restoring them after the upgrade process. + +.. seealso:: + :ref:`Server actions ` + +.. _upgrade/migration-scripts: + +Migration scripts +================= + +TODOUPG this page should be about migration scripts : + +#. What they are (python scripts that receives the psql cursor and the version) +#. What they are for : applying a modification on the data of your database when upgrading a module +#. In what circumstances you should use them : when changing the source code of your module between +2 versions of Odoo +#. How to write them : examples, upgrade-util package +#. The different phases and what is their impact: pre no ORM, before module is loaded so before +your new field gets created +#. Where to put them : in /migration**s** +#. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your +dump, run it and upgrade all modules via starting odoo-bin + +A migration script is a Python file containing a function called `migrate`, which the upgrade +process invokes at the appropriate time. Typically, this function executes one or multiple SQL +queries and can also access Odoo's ORM, as well as the `upgrade-util package +`__. + +.. example:: + Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model + in the standard code of Odoo. This change required the development of standard migration scripts + to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no + data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets + removed by another standard migration script. + +.. seealso:: + `DjangoProject.com documentation: Migrations + `_ + +.. spoiler:: Two migration scripts: adding "!" at the end of partners' names + + .. code-block:: python + + import logging + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + cr.execute( + """ + UPDATE res_partner + SET name = name || '!' + """ + ) + _logger.info("Updated %s partners", cr.rowcount) + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + env = util.env(cr) + + partners = env["res.partner"].search([]) + for partner in partners: + partner.name += "!" + + _logger.info("Updated %s partners", len(partners)) + +.. spoiler:: Migration script: fixing a Studio view + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + with util.edit_view(cr, "studio_customization.odoo_studio_project__e2f15f1a-2bdb-4003-a36e-ed731a1b9fae") as arch: + node = arch.xpath("""//xpath[@expr="//group[field[@name='activity_summary']]"]""")[0] + node.attrib["expr"] = "//field[@name='activity_summary']" + +.. note:: + Only Odoo's employees can modify migration scripts in the standard upgrade process on the upgrade + server. Third-party developers can develop custom migration scripts for their custom modules. + +Positioning a migration script +------------------------------ + +Migration scripts are executed depending on their module, the version of Odoo, the version of the +module, the phase of the migration script, and its name. The path of the file should follow this +template: :file:`/migrations/./{pre|post|end}-*.py` + +- :file:`` corresponds to the folder name of a module. For example, :file:`account` for + the Accounting module, or :file:`sale_subscription` for the Subscriptions module. +- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). +- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the + `Accounting module in Odoo 16 `_). +- :file:`` corresponds to :ref:`the phase of the migration script + `. +- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in + which it is executed for that module, version, and phase. + +.. _upgrade/migration-scripts-phases: + +Phases of migration scripts +--------------------------- + +The upgrade process consists of three phases for each version of each module: + + #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at + that time. + #. The post-phase, after the module and its dependencies are loaded and upgraded. + #. The end-phase, after all modules have been upgraded for that version. + +.. note:: + If you are unsure which phase to use, use the end-phase. + +Migration scripts are grouped according to the first part of their filenames into the corresponding +phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before +:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then +executed according to their lexical order. + +.. spoiler:: Execution order of example scripts for one module in one version + + - :file:`pre-zzz.py` + - :file:`pre-~do_something.py` + - :file:`post--testing.py` + - :file:`post-01-zzz.py` + - :file:`post-migrate.py` + - :file:`post-other_module.py` + - :file:`post-~migrate.py` + - :file:`end--migrate.py` + - :file:`end-01-migrate.py` + - :file:`end-aaa.py` + - :file:`end-~migrate.py` \ No newline at end of file diff --git a/content/developer/howtos/upgrading_customized_database.rst b/content/developer/howtos/upgrading_customized_database.rst deleted file mode 100644 index 2dde849b35..0000000000 --- a/content/developer/howtos/upgrading_customized_database.rst +++ /dev/null @@ -1,53 +0,0 @@ -:show-content: -:hide-page-toc: -:show-toc: - -=============================== -Upgrading a customized database -=============================== - -.. note:: - This page is intended to explain the technical aspects of Upgrading. For a more - general overview, please refer to the :doc:`upgrade documentation `. - -Upgrading a database that contains custom modules requires additional steps compared to -databases running the standard modules of Odoo since the source code of the custom modules -must be upgraded as well. - -For a custom module to be used in a database running the new version of Odoo, a new version of its -source code be compatible with the latest changes in the source code of Odoo must bereleased. -Those changes usually include fields, models, methods, or views being renamed or refactored. - -Renaming references might not be enough, as the :ref:`ORM ` would not be able to -differenciate a field being deleted and another being created, from a simple renaming of a field. -Therefore, you might have to write :ref:`custom migration scripts ` -to reflect certain changes in the source code of your custom modules to their corresponding data. - -For the standard modules of Odoo, the new version of its source code, with their migration -scripts, are published by Odoo alongside the release of the new version, while for custom modules, -the new version with its migration scripts must be developed by the maintainer of the module. - -.. important:: - When committing to upgrading custom modules, it is crucial to halt the development of new - features since they would have to be upgraded as well, and might create new issues during the - upgrade process. Once the new version of your module has been released, you may resume the - development. - -.. seealso:: - `Upgrade-util package `_ - -In a nutshell, upgrading your customized database requires the following steps: - -#. Halting the development of new customizations -#. Requesting an upgraded database and upgrading the custom modules' source code -#. Testing the upgraded modules on a new database, to catch any issue with the code -#. Testing the upgraded database with the new version of its modules, to catch any issue with the - data - -.. toctree:: - :maxdepth: 2 - - upgrade/migration_scripts - upgrade/upgrading_custom_modules - upgrade/upgrading_data - upgrade/upgrading_studio_customizations \ No newline at end of file From 2544ad5a26501b4cbb088946ed19f153c97186ef Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 16:04:45 +0100 Subject: [PATCH 07/12] [IMP] Upgrade technical documentation: adapt structure --- content/administration/upgrade.rst | 18 +- .../developer/howtos/upgrade_custom_db.rst | 332 +++++------------- content/developer/reference/backend.rst | 1 + 3 files changed, 98 insertions(+), 253 deletions(-) diff --git a/content/administration/upgrade.rst b/content/administration/upgrade.rst index eac8f33ab0..7ebf3044e6 100644 --- a/content/administration/upgrade.rst +++ b/content/administration/upgrade.rst @@ -44,8 +44,6 @@ An upgrade does not cover: modules, we recommend to parallelize the process by :ref:`requesting an upgraded database ` while also :doc:`upgrading the source code of your custom modules `. -.. TODOUPG : once the page for developers is published, uncomment and link -.. :doc:`first upgrade its source code ` Upgrading in a nutshell @@ -143,9 +141,8 @@ project `_. skipped, the upgraded database is built as soon as it is transferred from the upgrade platform, and the upgrade mode is exited. - Check out the :ref:`upgrade for developers' - documentation ` for more information. In - addition, if a module is not needed after an upgrade, :ref:`you can + Check out the :ref:`upgrading a customized database ` page for + more information. In addition, if a module is not needed after an upgrade, :ref:`you can remove customizations `. .. group-tab:: On-premise @@ -173,9 +170,8 @@ project `_. skipped, the upgraded database is built as soon as it is transferred from the upgrade platform, and the upgrade mode is exited. - Check out the :ref:`upgrade for developers' - documentation ` for more information. In - addition, if a module is not needed after an upgrade, :ref:`you can + Check out the :ref:`upgrading a customized database ` page for + more information. In addition, if a module is not needed after an upgrade, :ref:`you can remove customizations `. .. note:: @@ -302,8 +298,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: @@ -349,7 +345,7 @@ 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. - More information on how to upgrade your custom modules can be found in the :doc:``. + More information on how to upgrade your custom modules can be found on page :ref:``. .. group-tab:: On-premise diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst index 71caaf382d..f8c9cece5b 100644 --- a/content/developer/howtos/upgrade_custom_db.rst +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -1,88 +1,77 @@ :show-content: -:hide-page-toc: :show-toc: .. _upgrade/upgrade_custom_db: -============================= -Upgrade a customized database -============================= +=============================== +Upgrading a customized database +=============================== .. note:: - This page is intended to explain the technical aspects of Upgrading. For a more - general overview, please refer to the :doc:`upgrade documentation `. + This page is intended to explain the technical aspects of upgrading a database with non-standard + modules. For a more general overview, please refer to the + :doc:`upgrade documentation `. Upgrading a database that contains custom modules requires additional steps compared to databases running the standard modules of Odoo since the source code of the custom modules must be upgraded as well. -For a custom module to be used in a database running the new version of Odoo, a new version of its -source code be compatible with the latest changes in the source code of Odoo must bereleased. -Those changes usually include fields, models, methods, or views being renamed or refactored. - -Renaming references might not be enough, as the :ref:`ORM ` would not be able to -differenciate a field being deleted and another being created, from a simple renaming of a field. -Therefore, you might have to write :ref:`custom migration scripts ` -to reflect certain changes in the source code of your custom modules to their corresponding data. - -For the standard modules of Odoo, the new version of its source code, with their migration -scripts, are published by Odoo alongside the release of the new version, while for custom modules, -the new version with its migration scripts must be developed by the maintainer of the module. - .. important:: When committing to upgrading your custom database, it is crucial to halt the development of new features since they would have to be upgraded as well, and might create new issues later during the upgrade process. Once your upgrade is complete, you may resume their development. -.. seealso:: - `Upgrade-util package `_ - -In a nutshell, upgrading your customized database requires the following steps: - -#. :ref:`Requesting an upgraded database ` and upgrading the -custom modules' source code -#. Testing the upgraded modules on a new database, to catch any issue with the code -#. Testing the upgraded database with the new version of its modules, to catch any issue with the - data -#. Upgrading the production database (see :ref:`upgrade/upgrade-prod`) - -Upgrading custom modules -======================== - -TODOUPG this page should be about upgrading custom modules: -#. Why they are not compatible out of the box -#. The process of developing a new version of a custom module : make it installable on empty db, -upgrade a database using it to test the migration of data -#. How to find the derprecated elements -#. Don't forget to write migration scripts - Custom modules are usually not compatible out of the box with a new version of Odoo due to changes in the standard modules, such as models being merged, fields being renamed, or methods being refactored. Therefore, a new version of the modules must be created for each new version of Odoo, in which its source code is adapted to the new version. -To make the process of releasing a new version easier, we recommend exploring the new features -brought by the latest versions of Odoo to find out if any of your customizations have become -derprecated or can be replaced by a standard feature. +Our recommendation is to first assess your customization by comparing them to the features brought +by the new version of Odoo to detect any redundant customizations that can be removed from your +database, making your modules easier to maintain -.. example:: - In Odoo 15, the `sale.subscription` model has been merged into the `sale.order` module. Therefore, - any field added to the `sale.subscription` model must be ported over to the `sale.order` model. - Other references such as related fields, views, reports, etc., must also be updated to match the - new model name. +Then, make your custom modules installable on a new, empty database to ensure dependencies are +still correct, fields definitions are still valid, etc. This also require some :ref:`testing +` to ensure that all the features of your modules are still working properly. -Information on the changes between versions can be found in the `release notes -`_ and the :ref:`upgrade report `. +During that process, you can also :ref:`Request a test upgraded database +` to ensure the request can be successfully processed. + +Once your modules are installable and working properly (see +:ref:`Testing your database `), it is time to make them work on an upgraded +database to ensure that they do not depend on a previous installation (e.g., modules already +installed, data already present, etc.). During this process, you might have to develop +:ref:`migration scripts ` to reflect changes in the source code of +your custom modules to their corresponding data. + +After this step, it is crucial to do another :ref:`round of testing ` to +assess your database usability, as well as to detect any issue with the migrated data. + +At this stage, the rest of the upgrade process is the same as described in :doc:`/administration/upgrade`. .. seealso:: - :doc:`/developer/reference/user_interface/view_records` - :ref:`reference/fields` - :ref:`reference/orm/models` + - `Upgrade-util package `_ .. _upgrade/remove_customizations: -Removing customizations ------------------------ +Assessing your customizations +============================= + +Before upgrading your database, it is important to assess the features brought by the new version +of Odoo to determine if any of your customizations have become redundant and can be removed from +your database. + +.. example:: + In Odoo 15, the `sale.subscription` model has been merged into the `sale.order` module. Therefore, + any field added to the `sale.subscription` model must be ported over to the `sale.order` model. + Other references such as related fields, views, reports, etc., must also be updated to match the + new model name. + +Information on the changes between versions can be found in the `release notes +`_ and the :ref:`upgrade report `. Modules that have become redundant with the release of a new version of Odoo can be removed from your database with a :ref:`migration script ` using the @@ -103,8 +92,12 @@ using `remove_field`, `remove_model`, `remove_view`, etc., from the `upgrade-uti actions, etc., referring to a missing record will prevent them from working correctly and might block your processes in certain situations. -Upgrading custom fields and their data --------------------------------------- +Custom modules on an empty database +=================================== + +Installing custom modules on an empty database allows you to detect any discrepancies between the +source code of your modules and the new version of Odoo, such as missing dependencies in the +manifest, broken fields relations, views containing deprecated fields, etc. Any custom field that has a reference to a modified standard field must be adapted to the new version of Odoo. To find the corresponding field in the new version, we recommend looking at its @@ -120,62 +113,9 @@ your search. searching for another Many2one field in `account.move` related to `account.move`, for example, `in Odoo 16 `_. -.. note:: - Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. - However, this only renames the field and column names. Therefore, custom views, reports, field - relations, automated actions, etc., might still refer to the old field name and need to be - updated in the migration script as well. - -Upgrading models and methods definitions ----------------------------------------- - -Upgrading custom models consists mainly of ensuring that the module name and its inheritances -are correct. The :ref:`upgrade report ` and the `release notes -`_ can contain helpful information concerning various standard -models being changed or renamed. - -.. example:: - The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 - `_ - that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 - `_. - -If a custom model overrides standard methods, you must ensure that their name still matches the -name of the method they are overriding. In case of changes, you can search the method's source code -in the new version to find its new name. If the method has been refactored, the source code might -not exactly match, and a manual search is then required. - -Upgrading views definitions ---------------------------- - -Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's -`` tag, which can happen during a module update or when rendering it. - -Most of the time, the incompatibility of a custom view is expressed via an error when parsing the -view, which can happen during the update of a module or when rendering it. - -Custom views for custom models only require upgrading if the custom model has been changed. In -contrast, custom views inheriting from standard views can be impacted by changes in the standard -views. In this case, the custom views' source code requires an upgrade to be compatible with the new -version of its parent view. This can be done by retargetting the various Xpath expressions to match -an equivalent element that might have been moved or renamed. - -Testing the upgraded module -=========================== - -Once the source code of the custom modules has been upgraded, it is time to test them on a new -database to ensure that they does not depend on a previous installation (e.g., modules -already installed, data already present, etc.). This testing can help you detect issues with -your modules' dependencies, computed fields, etc. - -.. seealso:: - :ref:`Testing your database ` - -Upgrading data -============== - -Upgrading server, scheduled, and automated actions --------------------------------------------------- +.. important:: + Renaming fields in the source code of a module will not migrate the data from the old field to + the new one. This requires writing a :ref:`migration script `. References to fields in server, scheduled, and automated actions might be broken due to changes in the fields' definitions. This is usually the case for the actions :guilabel:`Execute Python Code`, :guilabel:`Create a @@ -187,148 +127,56 @@ Those actions are susceptible to being removed by the standard upgrade process, `intervention from an Odoo developer `_. Otherwise, it can be fixed with a custom `migration script `_. -.. note:: - To prevent actions from being removed, it is possible to preemptively change the reference(s) to - a field before upgrading and restoring them after the upgrade process. - .. seealso:: :ref:`Server actions ` -.. _upgrade/migration-scripts: - -Migration scripts -================= - -TODOUPG this page should be about migration scripts : - -#. What they are (python scripts that receives the psql cursor and the version) -#. What they are for : applying a modification on the data of your database when upgrading a module -#. In what circumstances you should use them : when changing the source code of your module between -2 versions of Odoo -#. How to write them : examples, upgrade-util package -#. The different phases and what is their impact: pre no ORM, before module is loaded so before -your new field gets created -#. Where to put them : in /migration**s** -#. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your -dump, run it and upgrade all modules via starting odoo-bin - -A migration script is a Python file containing a function called `migrate`, which the upgrade -process invokes at the appropriate time. Typically, this function executes one or multiple SQL -queries and can also access Odoo's ORM, as well as the `upgrade-util package -`__. +More rarely, models can also be renamed or merged into another model. In this case, if a custom +model inherits from the renamed or merged model, its inherit attributes must be updated to match the +new model name. .. example:: - Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model - in the standard code of Odoo. This change required the development of standard migration scripts - to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no - data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets - removed by another standard migration script. - -.. seealso:: - `DjangoProject.com documentation: Migrations - `_ - -.. spoiler:: Two migration scripts: adding "!" at the end of partners' names - - .. code-block:: python - - import logging - - _logger = logging.getLogger(__name__) - - - def migrate(cr, version): - cr.execute( - """ - UPDATE res_partner - SET name = name || '!' - """ - ) - _logger.info("Updated %s partners", cr.rowcount) - - .. code-block:: python - - import logging - from odoo.upgrade import util - - _logger = logging.getLogger(__name__) + - Between Odoo 12 and 13, the `account.invoice` model was merged into `account.move`. + - Between Odoo 15 and 16, the `sale.subscription` model was merged into `sale.order`. + - Between Odoo 15 and 16, the `account.analytic.group` model was renamed to `account.analytic.plan`. +If a custom model overrides standard methods, you must ensure that their name still matches the +name of the method they are overriding. In case of changes, you can search the method's source code +in the new version to find its new name. If the method has been refactored, the source code might +not exactly match, and a manual search is then required. The same goes for function calls to those methods. - def migrate(cr, version): - env = util.env(cr) - - partners = env["res.partner"].search([]) - for partner in partners: - partner.name += "!" - - _logger.info("Updated %s partners", len(partners)) - -.. spoiler:: Migration script: fixing a Studio view - - .. code-block:: python - - import logging - from odoo.upgrade import util - - _logger = logging.getLogger(__name__) - - - def migrate(cr, version): - with util.edit_view(cr, "studio_customization.odoo_studio_project__e2f15f1a-2bdb-4003-a36e-ed731a1b9fae") as arch: - node = arch.xpath("""//xpath[@expr="//group[field[@name='activity_summary']]"]""")[0] - node.attrib["expr"] = "//field[@name='activity_summary']" - -.. note:: - Only Odoo's employees can modify migration scripts in the standard upgrade process on the upgrade - server. Third-party developers can develop custom migration scripts for their custom modules. - -Positioning a migration script ------------------------------- +.. example:: + The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 + `_ + that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 + `_. -Migration scripts are executed depending on their module, the version of Odoo, the version of the -module, the phase of the migration script, and its name. The path of the file should follow this -template: :file:`/migrations/./{pre|post|end}-*.py` +Custom views are usually also impacted with the upgrade, as they may refer fields, models, or +other standard views that have been renamed or refactored. They should be adapted to the new +version of Odoo to avoid errors when loading them. -- :file:`` corresponds to the folder name of a module. For example, :file:`account` for - the Accounting module, or :file:`sale_subscription` for the Subscriptions module. -- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). -- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the - `Accounting module in Odoo 16 `_). -- :file:`` corresponds to :ref:`the phase of the migration script - `. -- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in - which it is executed for that module, version, and phase. +Once the source code of the custom modules has been upgraded, it is time to test them on a new +database to ensure that they does not depend on a previous installation (e.g., modules +already installed, data already present, etc.). This testing can help you detect issues with +your modules' dependencies, computed fields, etc. -.. _upgrade/migration-scripts-phases: +.. seealso:: + :ref:`Testing your database ` -Phases of migration scripts ---------------------------- +Custom modules on an upgraded database +====================================== -The upgrade process consists of three phases for each version of each module: +Reaching this step requires both the source code of your custom modules to be upgraded and a +successful :ref:`upgrade request `. If that is the case, you can +now test your modules on an upgraded database to ensure that the upgrade did not remove any +data, and that your modules are still working properly. - #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at - that time. - #. The post-phase, after the module and its dependencies are loaded and upgraded. - #. The end-phase, after all modules have been upgraded for that version. +When renaming fields in the process of upgrading the source code of your custom modules, the data +from the old field must be migrated to the new one. This can be done via a :ref:`migration script +` using the `rename_field` method from the `upgrade-util package +`_. +However, this only renames the field and column names. Therefore, custom views, reports, field +relations, automated actions, etc., might still refer to the old field name and need to be +updated in the migration script as well. -.. note:: - If you are unsure which phase to use, use the end-phase. - -Migration scripts are grouped according to the first part of their filenames into the corresponding -phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before -:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then -executed according to their lexical order. - -.. spoiler:: Execution order of example scripts for one module in one version - - - :file:`pre-zzz.py` - - :file:`pre-~do_something.py` - - :file:`post--testing.py` - - :file:`post-01-zzz.py` - - :file:`post-migrate.py` - - :file:`post-other_module.py` - - :file:`post-~migrate.py` - - :file:`end--migrate.py` - - :file:`end-01-migrate.py` - - :file:`end-aaa.py` - - :file:`end-~migrate.py` \ No newline at end of file +This is why it is crucial to do another :ref:`round of testing ` to ensure +that no data has been lost due to the upgrade of your custom modules. diff --git a/content/developer/reference/backend.rst b/content/developer/reference/backend.rst index cd56eca9c8..e9cc71870d 100644 --- a/content/developer/reference/backend.rst +++ b/content/developer/reference/backend.rst @@ -17,3 +17,4 @@ Python framework backend/testing backend/http backend/mixins + backend/migration_scripts From 81da6cdc76bb437e257161fbeba77b75f0a49857 Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 16:05:07 +0100 Subject: [PATCH 08/12] [IMP] Upgrade technical documentation: move mig script --- .../reference/backend/migration_scripts.rst | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 content/developer/reference/backend/migration_scripts.rst diff --git a/content/developer/reference/backend/migration_scripts.rst b/content/developer/reference/backend/migration_scripts.rst new file mode 100644 index 0000000000..c8746a882f --- /dev/null +++ b/content/developer/reference/backend/migration_scripts.rst @@ -0,0 +1,134 @@ +.. _upgrade/migration-scripts: + +================= +Migration scripts +================= + +TODOUPG this page should be about migration scripts : + +#. What they are (python scripts that receives the psql cursor and the version) +#. What they are for : applying a modification on the data of your database when upgrading a module +#. In what circumstances you should use them : when changing the source code of your module between +2 versions of Odoo +#. How to write them : examples, upgrade-util package +#. The different phases and what is their impact: pre no ORM, before module is loaded so before +your new field gets created +#. Where to put them : in /migration**s** +#. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your +dump, run it and upgrade all modules via starting odoo-bin + +A migration script is a Python file containing a function called `migrate`, which the upgrade +process invokes at the appropriate time. Typically, this function executes one or multiple SQL +queries and can also access Odoo's ORM, as well as the `upgrade-util package +`__. + +.. example:: + Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model + in the standard code of Odoo. This change required the development of standard migration scripts + to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no + data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets + removed by another standard migration script. + +.. seealso:: + `DjangoProject.com documentation: Migrations + `_ + +.. spoiler:: Two migration scripts: adding "!" at the end of partners' names + + .. code-block:: python + + import logging + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + cr.execute( + """ + UPDATE res_partner + SET name = name || '!' + """ + ) + _logger.info("Updated %s partners", cr.rowcount) + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + env = util.env(cr) + + partners = env["res.partner"].search([]) + for partner in partners: + partner.name += "!" + + _logger.info("Updated %s partners", len(partners)) + +.. spoiler:: Migration script: renaming a field + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + util.rename_field(cr, "account.analytic.line", "analytic_group", "analytic_plan_id") + + +Positioning a migration script +------------------------------ + +Migration scripts are executed depending on their module, the version of Odoo, the version of the +module, the phase of the migration script, and its name. The path of the file should follow this +template: :file:`/migrations/./{pre|post|end}-*.py` + +- :file:`` corresponds to the folder name of a module. For example, :file:`account` for + the Accounting module, or :file:`sale_subscription` for the Subscriptions module. +- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). +- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the + `Accounting module in Odoo 16 `_). +- :file:`` corresponds to :ref:`the phase of the migration script + `. +- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in + which it is executed for that module, version, and phase. + +.. _upgrade/migration-scripts-phases: + +Phases of migration scripts +--------------------------- + +The upgrade process consists of three phases for each version of each module: + + #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at + that time. + #. The post-phase, after the module and its dependencies are loaded and upgraded. + #. The end-phase, after all modules have been upgraded for that version. + +.. note:: + If you are unsure which phase to use, use the end-phase. + +Migration scripts are grouped according to the first part of their filenames into the corresponding +phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before +:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then +executed according to their lexical order. + +.. spoiler:: Execution order of example scripts for one module in one version + + - :file:`pre-zzz.py` + - :file:`pre-~do_something.py` + - :file:`post--testing.py` + - :file:`post-01-zzz.py` + - :file:`post-migrate.py` + - :file:`post-other_module.py` + - :file:`post-~migrate.py` + - :file:`end--migrate.py` + - :file:`end-01-migrate.py` + - :file:`end-aaa.py` + - :file:`end-~migrate.py` \ No newline at end of file From 804e3db9ba342c34afc40076c391746d59f5545e Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 16:19:01 +0100 Subject: [PATCH 09/12] [IMP] Upgrade technical documentation: fix warning and issues --- content/administration/upgrade.rst | 2 +- content/developer/howtos/upgrade_custom_db.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/administration/upgrade.rst b/content/administration/upgrade.rst index 7ebf3044e6..ef35023250 100644 --- a/content/administration/upgrade.rst +++ b/content/administration/upgrade.rst @@ -345,7 +345,7 @@ 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. - More information on how to upgrade your custom modules can be found on page :ref:``. + More information on how to upgrade your custom modules can be found on page :ref:`upgrading a customized database `. .. group-tab:: On-premise diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst index f8c9cece5b..7d68f3cd09 100644 --- a/content/developer/howtos/upgrade_custom_db.rst +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -78,8 +78,8 @@ from your database with a :ref:`migration script ` us `uninstall_module` method from the `upgrade-util package `__. If only a few elements of a module have become redundant, it is possible to remove them one by one -using `remove_field`, `remove_model`, `remove_view`, etc., from the `upgrade-util package -__`. +using `remove_field`, `remove_model`, `remove_view`, etc., from the +`upgrade-util package __`. .. warning:: Don't forget that fields, models, and views can still be referenced in other records such as @@ -172,8 +172,8 @@ data, and that your modules are still working properly. When renaming fields in the process of upgrading the source code of your custom modules, the data from the old field must be migrated to the new one. This can be done via a :ref:`migration script -` using the `rename_field` method from the `upgrade-util package -`_. +` using the `rename_field` method from the +`upgrade-util package `__. However, this only renames the field and column names. Therefore, custom views, reports, field relations, automated actions, etc., might still refer to the old field name and need to be updated in the migration script as well. From 7807f1b9e6941ea80763d91fb67ac64f2979f311 Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Mon, 27 Nov 2023 16:21:14 +0100 Subject: [PATCH 10/12] [IMP] Upgrade technical documentation : refer to migration script --- content/developer/howtos/upgrade_custom_db.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst index 7d68f3cd09..224f59577f 100644 --- a/content/developer/howtos/upgrade_custom_db.rst +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -84,7 +84,7 @@ using `remove_field`, `remove_model`, `remove_view`, etc., from the .. warning:: Don't forget that fields, models, and views can still be referenced in other records such as automated and server actions, mail templates, filters, etc. . Those references must be found - and removed from the database, preferably in the same migration script. + and removed from the database, preferably in the same :ref:`migration script `. .. important:: :ref:`Testing your database ` is crucial, especially when removing @@ -176,7 +176,7 @@ from the old field must be migrated to the new one. This can be done via a :ref: `upgrade-util package `__. However, this only renames the field and column names. Therefore, custom views, reports, field relations, automated actions, etc., might still refer to the old field name and need to be -updated in the migration script as well. +updated in the :ref:`migration script ` as well. This is why it is crucial to do another :ref:`round of testing ` to ensure that no data has been lost due to the upgrade of your custom modules. From 30acbb1d114d1fa468235ae84154d3b2f2e19689 Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Tue, 28 Nov 2023 08:35:11 +0100 Subject: [PATCH 11/12] [IMP] Upgrade technical documentation: add last chapter --- content/developer/howtos/upgrade_custom_db.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst index 224f59577f..b7fdd4cab1 100644 --- a/content/developer/howtos/upgrade_custom_db.rst +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -180,3 +180,14 @@ updated in the :ref:`migration script ` as well. This is why it is crucial to do another :ref:`round of testing ` to ensure that no data has been lost due to the upgrade of your custom modules. + +Rehearsal, testing, and production upgrade +========================================== + +At this stage, we recommend to do a rehearsal upgrade on a copy of your production database to +ensure that the upgrade process is still working as expected, especially if you haven't done an +upgrade request in a while. + +Once you are confident that upgrading your database will not cause any issue, you can proceed with +the upgrade of your production database by following the process described on the +:doc:`/administration/upgrade` page. \ No newline at end of file From 75594bb01d062b004cc078cca2569a1d3d039fd6 Mon Sep 17 00:00:00 2001 From: "Nathan Marotte (nama)" Date: Thu, 30 Nov 2023 12:51:46 +0100 Subject: [PATCH 12/12] [UPG] Upgrade technical documentation: put notes in comment --- .../howtos/upgrade/migration_scripts.rst | 23 +++++++++--------- .../developer/howtos/upgrade_custom_db.rst | 5 ++-- .../reference/backend/migration_scripts.rst | 24 +++++++++---------- 3 files changed, 27 insertions(+), 25 deletions(-) diff --git a/content/developer/howtos/upgrade/migration_scripts.rst b/content/developer/howtos/upgrade/migration_scripts.rst index be33ab369f..b2c4459536 100644 --- a/content/developer/howtos/upgrade/migration_scripts.rst +++ b/content/developer/howtos/upgrade/migration_scripts.rst @@ -4,17 +4,18 @@ Migration scripts ================= -TODOUPG this page should be about migration scripts : -#. What they are (python scripts that receives the psql cursor and the version) -#. What they are for : applying a modification on the data of your database when upgrading a module -#. In what circumstances you should use them : when changing the source code of your module between -2 versions of Odoo -#. How to write them : examples, upgrade-util package -#. The different phases and what is their impact: pre no ORM, before module is loaded so before -your new field gets created -#. Where to put them : in /migration**s** -#. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your -dump, run it and upgrade all modules via starting odoo-bin +TODOUPG See comments in the code for NAMA notes (what this page should be about) + +.. #. What they are (python scripts that receives the psql cursor and the version) +.. #. What they are for : applying a modification on the data of your database when upgrading a module +.. #. In what circumstances you should use them : when changing the source code of your module between +.. 2 versions of Odoo +.. #. How to write them : examples, upgrade-util package +.. #. The different phases and what is their impact: pre no ORM, before module is loaded so before +.. your new field gets created +.. #. Where to put them : in /migration**s** +.. #. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your +.. dump, run it and upgrade all modules via starting odoo-bin A migration script is a Python file containing a function called `migrate`, which the upgrade process invokes at the appropriate time. Typically, this function executes one or multiple SQL diff --git a/content/developer/howtos/upgrade_custom_db.rst b/content/developer/howtos/upgrade_custom_db.rst index b7fdd4cab1..1fb851d651 100644 --- a/content/developer/howtos/upgrade_custom_db.rst +++ b/content/developer/howtos/upgrade_custom_db.rst @@ -33,14 +33,15 @@ database, making your modules easier to maintain Then, make your custom modules installable on a new, empty database to ensure dependencies are still correct, fields definitions are still valid, etc. This also require some :ref:`testing ` to ensure that all the features of your modules are still working properly. +This step is important to determine if your modules are working by themselves, and not +relying on any data or installed apps already present in the database. During that process, you can also :ref:`Request a test upgraded database ` to ensure the request can be successfully processed. Once your modules are installable and working properly (see :ref:`Testing your database `), it is time to make them work on an upgraded -database to ensure that they do not depend on a previous installation (e.g., modules already -installed, data already present, etc.). During this process, you might have to develop +database. During this process, you might have to develop :ref:`migration scripts ` to reflect changes in the source code of your custom modules to their corresponding data. diff --git a/content/developer/reference/backend/migration_scripts.rst b/content/developer/reference/backend/migration_scripts.rst index c8746a882f..3c281d52c1 100644 --- a/content/developer/reference/backend/migration_scripts.rst +++ b/content/developer/reference/backend/migration_scripts.rst @@ -4,18 +4,18 @@ Migration scripts ================= -TODOUPG this page should be about migration scripts : - -#. What they are (python scripts that receives the psql cursor and the version) -#. What they are for : applying a modification on the data of your database when upgrading a module -#. In what circumstances you should use them : when changing the source code of your module between -2 versions of Odoo -#. How to write them : examples, upgrade-util package -#. The different phases and what is their impact: pre no ORM, before module is loaded so before -your new field gets created -#. Where to put them : in /migration**s** -#. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your -dump, run it and upgrade all modules via starting odoo-bin +TODOUPG See comments in the code for NAMA notes (what this page should be about) + +.. #. What they are (python scripts that receives the psql cursor and the version) +.. #. What they are for : applying a modification on the data of your database when upgrading a module +.. #. In what circumstances you should use them : when changing the source code of your module between +.. 2 versions of Odoo +.. #. How to write them : examples, upgrade-util package +.. #. The different phases and what is their impact: pre no ORM, before module is loaded so before +.. your new field gets created +.. #. Where to put them : in /migration**s** +.. #. How to test them Odoo SH : branch in upgrade mode, push a commit, On-premise: receive your +.. dump, run it and upgrade all modules via starting odoo-bin A migration script is a Python file containing a function called `migrate`, which the upgrade process invokes at the appropriate time. Typically, this function executes one or multiple SQL