17.0 upgrade doc p2 3171474 nama

content/administration/upgrade.rst

@@ -39,10 +39,11 @@ An upgrade does not cover:
   - Migrating from another ERP to Odoo
 
 .. warning::
-   If your database contains a **custom module**, you must first upgrade its source code to be
-   compatible with the new version of Odoo **before upgrading**.
-.. TODOUPG : once the page for developers is published, uncomment and link
-.. :doc:`first upgrade its source code </developer/reference/upgrade>`
+   If your database contains custom modules, it cannot be upgraded until a version of your custom
+   modules is available for the target version of Odoo. For customers maintaining their own custom
+   modules, we recommend to parallelize the process by :ref:`requesting an upgraded database
+   <upgrade/request-test-database>` while also :doc:`upgrading the source code of your custom
+   modules </developer/howtos/upgrade_custom_db>`.
 
 
 Upgrading in a nutshell
@@ -51,15 +52,15 @@ Upgrading in a nutshell
 #. Request an upgraded test database (see :ref:`obtaining an upgraded test database
    <upgrade/request-test-database>`).
 
+#. If applicable : upgrade the source code of your custom module to be compatible with the new
+   version of Odoo (see :doc:`/developer/howtos/upgrade_custom_db`).
+
 #. Thoroughly test the upgraded database (see :ref:`testing the new version of the database
    <upgrade/test_your_db>`).
 
 #. Report any issue encountered during the testing to Odoo via the `support page
    <https://odoo.com/help?stage=migration>`__.
 
-#. (If applicable) : upgrade the source code of your custom module to be compatible with the new
-   version of Odoo.
-
 #. Once all issues are resolved and you are confident that the upgraded database can be used as
    your main database without any issues, plan the upgrade of your production database.
 
@@ -69,9 +70,6 @@ Upgrading in a nutshell
 #. Report any issue encountered during the upgrade to Odoo via the `support page
    <https://odoo.com/help?stage=post_upgrade>`__.
 
-.. TODOUPG: Once the page for developers is published, put this at 4)
-.. (see :ref:`upgrading customizations <upgrade/upgrading_customizations>`).
-
 .. _upgrade/request-test-database:
 
 Obtaining an upgraded test database
@@ -136,18 +134,16 @@ project <https://odoo.sh/project>`_.
       file of the upgrade process can be found in your newly upgraded staging build by going to
       :file:`~/logs/upgrade.log`.
 
-      .. note::
+      .. important::
          In databases where custom modules are installed, their source code
          must be up-to-date with the target version of Odoo before the upgrade
          can be performed. If there are none, the "update on commit" mode is
          skipped, the upgraded database is built as soon as it is transferred from the upgrade
          platform, and the upgrade mode is exited.
 
-         .. TODOUPG : once the page for developers is published, uncomment
-         .. Check out the :doc:`upgrade for developers'
-         .. documentation </developer/reference/upgrade>` for more information. In
-         .. addition, if a module is not needed after an upgrade, :ref:`you can
-         .. remove customizations <upgrade/remove_customizations>`.
+         Check out the :ref:`upgrading a customized database <upgrade/upgrade_custom_db>` page for
+         more information. In addition, if a module is not needed after an upgrade, :ref:`you can
+         remove customizations <upgrade/remove_customizations>`.
 
    .. group-tab:: On-premise
 
@@ -167,6 +163,17 @@ project <https://odoo.sh/project>`_.
       An upgraded test database can also be requested via the `Upgrade page
       <https://upgrade.odoo.com/>`_.
 
+      .. important::
+         In databases where custom modules are installed, their source code
+         must be up-to-date with the target version of Odoo before the upgrade
+         can be performed. 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:`upgrading a customized database <upgrade/upgrade_custom_db>` page for
+         more information. In addition, if a module is not needed after an upgrade, :ref:`you can
+         remove customizations <upgrade/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
@@ -291,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:
@@ -338,8 +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.
-   .. TODOUPG : once the page for developers is published, uncomment
-   .. More information on how to upgrade your custom modules can be found in the :ref:`upgrading customizations documentation <upgrade/upgrading_customizations>`.
+      More information on how to upgrade your custom modules can be found on page :ref:`upgrading a customized database <upgrade/upgrade_custom_db>`.
 
    .. group-tab:: On-premise
 

content/developer/howtos.rst

@@ -20,6 +20,7 @@ How-to guides
     howtos/translations
     howtos/website_themes
     howtos/connect_device
+    howtos/upgrade_custom_db
 
 .. 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:: Upgrading a customized database
+      :target: howtos/upgrade_custom_db
+
+      Learn how to upgrade a customized database, as well as the code and data of its custom modules.

content/developer/howtos/upgrade/migration_scripts.rst

@@ -0,0 +1,139 @@
+.. _upgrade/migration-scripts:
+
+=================
+Migration scripts
+=================
+
+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 <module_name>/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
+<https://github.com/odoo/upgrade-util/>`__.
+
+.. 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
+   <https://docs.djangoproject.com/en/4.2/topics/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:`<module_name>/migrations/<major_version>.<minor_version>/{pre|post|end}-*.py`
+
+- :file:`<module_name>` 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:`<major_version>` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16).
+- :file:`<minor_version>` corresponds to the minor version of the module (e.g., :file:`1.2` for the
+  `Accounting module in Odoo 16 <https://github.com/odoo/odoo/blob/c8a738610778d110734ca5b9b9cfe8723f70f8ce/addons/account/__manifest__.py#L5C17-L5C22>`_).
+- :file:`<pre|post|end>` corresponds to :ref:`the phase of the migration script
+  <upgrade/migration-scripts-phases>`.
+- :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`