|
| 1 | +============================= |
| 2 | +Upgrade a customized database |
| 3 | +============================= |
| 4 | + |
| 5 | +Upgrading to a new version of Odoo can be challenging, especially if the database you work on |
| 6 | +contains custom modules. This page intent is to explain the technical process of upgrading a |
| 7 | +database with customized modules. Refer to :doc:`Upgrade documentation </administration/upgrade>` |
| 8 | +for guidance on how to upgrade a database without customized modules. |
| 9 | + |
| 10 | +We consider a custom module, any module that extends the standard code of Odoo and that was not |
| 11 | +built with the Studio app. Before upgrading such a module, or before requesting its upgrade, have a |
| 12 | +look at the :ref:`upgrade/sla` to make sure who's responsible for it. |
| 13 | + |
| 14 | +While working on what we refer to as the **custom upgrade** of your database, keep in mind the goals |
| 15 | +of an upgrade: |
| 16 | + |
| 17 | +#. Stay supported |
| 18 | +#. Get the latest features |
| 19 | +#. Enjoy the performance improvement |
| 20 | +#. Reduce the technical debt |
| 21 | +#. Benefit from security improvements |
| 22 | + |
| 23 | +With every new version of Odoo, changes are introduced. These changes can impact modules on which |
| 24 | +customization have been developed. This is the reason why upgrading a database that contains custom |
| 25 | +modules requires additional steps in order to upgrade the source code. |
| 26 | + |
| 27 | +These are the steps to follow to upgrade customized databases: |
| 28 | + |
| 29 | +#. :ref:`Stop the devolopments and challenge them <upgrade_custom/stop_developments>`. |
| 30 | +#. :ref:`Request an upgraded database <upgrade_custom/request_upgrade>`. |
| 31 | +#. :ref:`Make your module installable on an empty database <upgrade_custom/empty_database>`. |
| 32 | +#. :ref:`Make your module installable on the upgraded database <upgrade_custom/upgraded_database>`. |
| 33 | +#. :ref:`Test extensively and do a rehearsal <upgrade_custom/testing_rehearsal>`. |
| 34 | +#. :ref:`Upgrade the production database <upgrade_custom/production>`. |
| 35 | + |
| 36 | + |
| 37 | +.. _upgrade_custom/stop_developments: |
| 38 | + |
| 39 | +Step 1: Stop the developments |
| 40 | +============================= |
| 41 | + |
| 42 | +Starting an upgrade requires commitment and development resources. If developments keep being made |
| 43 | +at the same time, those features will need to be re-upgraded and tested every time you change them. |
| 44 | +This is why we recommend a complete freeze of the codebase when starting the upgrade process. |
| 45 | +Needless to say, bug fixing is exempt from this recommendation. |
| 46 | + |
| 47 | +Once you have stopped development, it is a good practice to assess the developments made and compare |
| 48 | +them with the features introduced between your current version and the version you are targeting. |
| 49 | +Challenge the developments as much as possible and find functional workarounds. Removing redundancy |
| 50 | +between your developments and the standard version of Odoo will lead to an eased |
| 51 | +upgrade process and reduce technical debt. |
| 52 | + |
| 53 | +.. note:: |
| 54 | + You can find information on the changes between versions in the `Release Notes |
| 55 | + <https:/odoo.com/page/release-notes>`_. |
| 56 | + |
| 57 | + |
| 58 | +.. _upgrade_custom/request_upgrade: |
| 59 | + |
| 60 | +Step 2: Request an upgraded database |
| 61 | +==================================== |
| 62 | + |
| 63 | +Once the developments have stopped for the custom modules and the implemented features have been |
| 64 | +challenged to remove redundancy and unnecessary code, the next step is to request an upgraded test |
| 65 | +database. To do so, follow the steps mentioned in :ref:`upgrade/request-test-database`, depending on |
| 66 | +the hosting type of your database. |
| 67 | + |
| 68 | +The purpose of this stage is not to start working with the custom modules in the upgraded database, |
| 69 | +but to make sure the standard upgrade process works seamlessly, and the test database is delivered |
| 70 | +properly. If that's not the case, and the upgrade request fails, request the assistance of Odoo via |
| 71 | +the `support page <https://odoo.com/help?stage=migration>`_ by selecting the option related to |
| 72 | +testing the upgrade. |
| 73 | + |
| 74 | + |
| 75 | +.. _upgrade_custom/empty_database: |
| 76 | + |
| 77 | +Step 3: Empty database |
| 78 | +====================== |
| 79 | + |
| 80 | +Before working on an upgraded test database, we recommend to make the custom developments work on an |
| 81 | +empty database in the targeted version of your upgrade. This ensures that the customization is |
| 82 | +compatible with the new version of Odoo, allows to analyze how it behaves and interacts with the new |
| 83 | +features, and guarantees that they will not cause any issues when upgrading the database. |
| 84 | + |
| 85 | +Making the custom modules work in an empty database also helps avoid changes and wrong |
| 86 | +configurations that might be present in the production database (like studio customization, |
| 87 | +customized website pages, email templates or translations). They are not intrinsically related to |
| 88 | +the custom modules and that can raise unwanted issues in this stage of the upgraded process. |
| 89 | + |
| 90 | +To make custom modules work on an empty database we advise to follow these steps: |
| 91 | + |
| 92 | +#. :ref:`upgrade_custom/empty_database/modules_installable` |
| 93 | +#. :ref:`upgrade_custom/empty_database/test_fixes` |
| 94 | +#. :ref:`upgrade_custom/empty_database/clean_code` |
| 95 | +#. :ref:`Make standard tests run successfully <upgrade_custom/empty_database/standard_test>` |
| 96 | + |
| 97 | +.. _upgrade_custom/empty_database/modules_installable: |
| 98 | + |
| 99 | +Make custom modules installable |
| 100 | +------------------------------- |
| 101 | + |
| 102 | +The first step is to make the custom modules installable in the new Odoo version. |
| 103 | +This means, starting by ensuring there are no tracebacks or warnings during their installation. |
| 104 | +For this, install the custom modules, one by one, in an empty database of the new Odoo version and |
| 105 | +fix the tracebacks and warnings that arise from that. |
| 106 | + |
| 107 | +This process will help detect issues during the installation of the modules. For example: |
| 108 | + |
| 109 | +- Invalid module dependencies. |
| 110 | +- Syntax change: assets declaration, OWL updates, attrs. |
| 111 | +- References to standard fields, models, views not existing anymore or renamed. |
| 112 | +- Xpath that moved or were removed from views. |
| 113 | +- Methods renamed or removed. |
| 114 | +- ... |
| 115 | + |
| 116 | +.. _upgrade_custom/empty_database/test_fixes: |
| 117 | + |
| 118 | +Test and fixes |
| 119 | +-------------- |
| 120 | + |
| 121 | +Once there are no more tracebacks when installing the modules, the next step is to test them. |
| 122 | +Even if the custom modules are installable on an empty database, this does not guarantee there are |
| 123 | +no errors during their execution. Because of this, we encourage to test thoroughly all the |
| 124 | +customization to make sure everything is working as expected. |
| 125 | + |
| 126 | +This process will help detect further issues that are not identified during the module installation |
| 127 | +and can only be detected in runtime. For example, deprecated calls to standard python or OWL |
| 128 | +functions, non-existing references to standard fields, etc. |
| 129 | + |
| 130 | +We recommend to test all the customization, especially the following elements: |
| 131 | + |
| 132 | +- Views |
| 133 | +- Email templates |
| 134 | +- Reports |
| 135 | +- Server actions and automated actions |
| 136 | +- Changes in the standard workflows |
| 137 | +- Computed fields |
| 138 | + |
| 139 | +We also encourage to write automated tests to save time during the testing iterations, increase the |
| 140 | +test coverage, and ensure that the changes and fixes introduced do not break the existing flows. |
| 141 | +If there are tests already implemented in the customization, make sure they are upgraded to the new |
| 142 | +Odoo version and run successfully, fixing issues that might be present. |
| 143 | + |
| 144 | +.. _upgrade_custom/empty_database/clean_code: |
| 145 | + |
| 146 | +Clean the code |
| 147 | +-------------- |
| 148 | + |
| 149 | +At this stage of the upgrade process, we also suggest to clean the code as much as possible. |
| 150 | +This includes: |
| 151 | + |
| 152 | +- Remove redundant and unnecessary code. |
| 153 | +- Remove features that are now part of Odoo standard, as described in |
| 154 | + :ref:`upgrade_custom/stop_developments`. |
| 155 | +- Clean commented code if it is not needed anymore. |
| 156 | +- Refactor the code (functions, fields, views, reports, etc.) if needed. |
| 157 | + |
| 158 | +.. _upgrade_custom/empty_database/standard_test: |
| 159 | + |
| 160 | +Standard tests |
| 161 | +-------------- |
| 162 | + |
| 163 | +Once the previous steps are completed, we advise to make sure all standard tests associated to the |
| 164 | +dependencies of the custom module pass. |
| 165 | +Standard tests ensure the validation of the code logic and prevent data corruption. |
| 166 | +They will help you identify bugs or unwanted behavior before you work on your database. |
| 167 | + |
| 168 | +In case there are standard test failing, we suggest to analyze the reason for their failure: |
| 169 | + |
| 170 | +- The customization changes the standard workflow: Adapt the standard test to your workflow. |
| 171 | +- The customization did not take into account a special flow: Adapt your customization to ensure it |
| 172 | + works for all the standard workflows. |
| 173 | + |
| 174 | + |
| 175 | +.. _upgrade_custom/upgraded_database: |
| 176 | + |
| 177 | +Step 4: Upgraded database |
| 178 | +========================= |
| 179 | + |
| 180 | +Once the custom modules are installable and working properly in an empty database, it is time to |
| 181 | +make them work on an :ref:`upgraded database <upgrade/request-test-database>`. |
| 182 | + |
| 183 | +To make sure the custom code is working flawlessly in the new version, follow these steps: |
| 184 | + |
| 185 | +- :ref:`upgrade_custom/upgraded_database/migrate_data` |
| 186 | +- :ref:`upgrade_custom/upgraded_database/test_custom` |
| 187 | + |
| 188 | +.. _upgrade_custom/upgraded_database/migrate_data: |
| 189 | + |
| 190 | +Migrate the data |
| 191 | +---------------- |
| 192 | + |
| 193 | +During the upgrade of the custom modules, you might have to use migration scripts to reflect changes |
| 194 | +from the source code to their corresponding data. |
| 195 | + |
| 196 | +- Any technical data that was renamed during the upgrade of the custom code (models, fields, |
| 197 | + external identifiers) should be renamed using migration scripts to avoid data loss during the |
| 198 | + module upgrade. |
| 199 | +- Data from standard models removed from the source code of the newer Odoo version and from the |
| 200 | + database during the standard upgrade process might need to be recovered from the old model table |
| 201 | + if it is still present. |
| 202 | + |
| 203 | +Migration scripts can also be used to: |
| 204 | + |
| 205 | +- Ease the processing time of an upgrade. For example, to store the value of computed stored fields |
| 206 | + on models with an excessive number of records by using SQL queries. |
| 207 | +- Recompute fields in case the computation of their value has changed. |
| 208 | +- Uninstall unwanted custom modules. |
| 209 | +- Correct faulty data or wrong configurations. |
| 210 | + |
| 211 | +.. _upgrade_custom/upgraded_database/test_custom: |
| 212 | + |
| 213 | +Test the custom modules |
| 214 | +----------------------- |
| 215 | + |
| 216 | +To make sure the custom modules work properly with your data in the upgraded database, they need to |
| 217 | +be tested as well. This helps ensure both the standard and the custom data stored in the database |
| 218 | +are consistent and that nothing was lost during the upgrade process. |
| 219 | + |
| 220 | +Things to pay attention to: |
| 221 | + |
| 222 | +- Views not working: During the upgrade, if a view causes issues because of its content, it gets |
| 223 | + disabled. You can find the information on disabled views on the :ref:`Upgrade report |
| 224 | + <upgrade/upgrade_report>`. This view needs to be activated again. To achieve this, we recommend |
| 225 | + the use of migration scripts. |
| 226 | +- :doc:`Module data <../tutorials/define_module_data>` not updated: Custom records that have the |
| 227 | + ``noupdate`` flag are not updated when upgrading the module in the new database. For the custom |
| 228 | + data that needs to be updated due to changes in the new version, we recommend to use migration |
| 229 | + scripts to do so. |
| 230 | + |
| 231 | + |
| 232 | +.. _upgrade_custom/testing_rehearsal: |
| 233 | + |
| 234 | +Step 5: Testing and rehearsal |
| 235 | +============================= |
| 236 | + |
| 237 | +When the custom modules are working properly in the upgraded database, it is crucial to do another |
| 238 | +round of testing to assess the database usability and detect any issues that might have gone |
| 239 | +unnoticed in previous tests. For further information about testing the upgraded database, check |
| 240 | +:ref:`upgrade/test_your_db`. |
| 241 | + |
| 242 | +As mentioned in :ref:`upgrade/upgrade-prod`, both standard upgrade scripts and your database are |
| 243 | +constantly evolving. Therefore it is highly recommended to frequently request new upgraded test |
| 244 | +databases and ensure that the upgrade process is still successful. |
| 245 | + |
| 246 | +In addition to that, make a full rehearsal of the upgrade process the day before upgrading the |
| 247 | +production database to avoid undesired behavior during the upgrade and to detect any issue that |
| 248 | +might have occurred with the migrated data. |
| 249 | + |
| 250 | + |
| 251 | +.. _upgrade_custom/production: |
| 252 | + |
| 253 | +Step 6: Production upgrade |
| 254 | +========================== |
| 255 | + |
| 256 | +Once you are confident about upgrading your production database, follow the process described on |
| 257 | +:ref:`upgrade/upgrade-prod`, depending on the hosting type of your database. |
0 commit comments