Migration to version 16.0

Before migrating

• Update yourself with the latest OCA Conventions: https://odoo-community.org/page/contributing
• Subscribe to the mailing list of the related project: https://odoo-community.org/groups
• On the corresponding GitHub issue inside the repository named "Migration to version 16.0", announce which module(s) you want to migrate
• Install pre-commit

Tasks to do in the migration

REMARK: Here, we are highlighting framework changes from previous version to this one, not data-model changes, as they are very extensive, and the alternative may depends on the module requirements. You can check data-model changes for each core module in the upgrade_analysis.txt files inside OpenUpgrade project: https://github.com/OCA/OpenUpgrade.

REMARK 2: If you are doing a migration jumping several versions, please check all the tasks in the successive "Migration to version XX.0" guides until arriving to this one.

• Bump module version to 16.0.1.0.0.
• Remove any possible migration script from previous version (in a nutshell, remove migrations folder inside the module if exists).
• Squash administrative commits (if any) with the previous commit for reducing commit noise. Check https://github.com/OCA/maintainer-tools/wiki/Merge-commits-in-pull-requests#mergesquash-the-commits-generated-by-bots-or-weblate for details.
• Check if the maturity level of the module can be improved in this version.
• If you are overriding name_search method in your module, you may make use now of new _rec_names_search class variable to expose the fields to search for without requiring the method override. More details at https://github.com/odoo/odoo/commit/3155c3e425581b71491844e7f9a3dd76a9f245a4.
• Any view with groups_id on it now has to move such groups to the elements of the view. But now you can put groups attribute in a view field instead of isolating it on a view without fear of an access error. Check it in https://github.com/odoo/odoo/pull/98551.
• On the same mood, you should check if the fields protected by a group interact in some way with business logic or UI. For example, a field being part of a domain of another field, or being used in copy/defaults. An special case is the field company_id, which is always used internally for domains on many2one fields referencing multi-company aware records. On these cases, you have to add the same field twice, one with the group, and another invisible without it. Check core examples in https://github.com/odoo/odoo/pull/95729.
• One2many fields outside of a notebook are now not expanding to the full form width by default. You should put colspan="2" for achieving such effect. Example: https://github.com/OCA/bank-payment/commit/e95d794aef37ab25239efd7a2e75793b39f81928#diff-7fb1d0b06e216bc7b8ebd1553323de7cd5cda01c9199ad4bd707007cbfb92251R59
• If using fields_get_keys() method for getting fields definition, now use directly _fields variable or get_views() method.
• The method fields_view_get should be replaced by get_view. Example: https://github.com/odoo/odoo/commit/b03c227e885efa4ccdcad43ccb56ee10371b9284#diff-9d31094bdf7f812b4cc4adc3498384e42cc6477ada91f39ff7c33decf8b7268fR23
• If using get_xml_id() method for getting an ID, now use the method get_external_id().
• The methods flush() and recompute() are deprecated. Use flush_model(), flush_recordset() or env.flush_all() instead depending on the needed granularity.
• The methods refresh() and invalidate_cache() are deprecated. Use invalidate_model(), invalidate_recordset() or env.invalidate_all() instead depending on the needed granularity.
• You can now use more type of indexes in fields depending on the purpose. Check them on https://github.com/odoo/odoo/blob/fa8fc5b26b948a9da4013874fb5af2d84ddb98c6/odoo/fields.py#L125-L133. True value can be replaced by btree to be more expressive.
• XML assets templates are now added into regular asset bundles. Previously, they were added to the fake asset bundle web.assets_qweb, but now, they should be declared in their proper assets bundle that fits their scope (web.assets_backend, web.assets_frontend, etc). You can check plenty of examples in the original refactor: odoo/odoo#95500.
• Put unaccent=False on field definitions where no distinction should be made between accented words, for getting better performance on searches. Example: parent_path field. See https://github.com/odoo/odoo/pull/76436 for more details.
• Reports, QWeb template and website elements should be adapted if they use some Bootstrap 4 elements, as now Odoo is using Bootstrap 5. You can use the convert_string_bootstrap_4to5 openupgradelib method passing the HTML fragment string for getting it automatically converted.
• Add tests to increase code coverage.
• If there's a test class using setUp to generate test records, move it to setUpClass as it's way more performant since it runs only once.
• If there's a method calling super in the module, check that the method is still there on upstream dependencies and it's not dead code.
• If there's a method overriding, check that the signature and keywords are maintained in this version, or adapt it conveniently.
• Check past migration guides for things not done in previous migrations.
• Do the rest of the changes you need to do for making the module works on new version.

Tasks NOT to do in the migration

• change copyright year

A line like this:

# Copyright 2017 ACME Ltd - Johnny Glamour

says "copyright FROM 2017". There's no need to change the year to the current year.

• change original authors

How-to

Technical method to migrate a module from "15.0" to "16.0" branch

• $repo: the OCA repository hosting the module
• $module: the name of the module you want to migrate
• $user_org: your GitHub login or organization name

Full process

• On a shell command:

  $ git clone https://github.com/OCA/$repo -b 16.0
  $ cd $repo
  $ git checkout -b 16.0-mig-$module origin/16.0
  $ git format-patch --keep-subject --stdout origin/16.0..origin/15.0 -- $module | git am -3 --keep
  $ pre-commit run -a  # to run black, isort and prettier (ignore pylint errors at this stage)
  $ git add -A
  $ git commit -m "[IMP] $module: pre-commit stuff"  --no-verify  # it is important to do all formatting in one commit the first time

• Check https://github.com/OCA/maintainer-tools/wiki/Merge-commits-in-pull-requests for a procedure for reducing commits from "OCA Transbot...".
• Adapt the module to the 16.0 version following tasks to do.
• On a shell command, type this for uploading the content to GitHub:

  $ git add --all
  $ git commit -m "[MIG] $module: Migration to 16.0"
  $ git remote add $user_org [email protected]:$user_org/$repo.git # This mode requires an SSH key in the GitHub account
  $ ... or ....
  $ git remote add $user_org https://github.com/$user_org/$repo.git # This will required to enter user/password each time
  $ git push $user_org 16.0-mig-$module --set-upstream

• Follow the link on the command line or check in https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork how to create the pull request.
• For being easily searchable and avoiding to duplicate efforts, please name the pull request following this pattern: [16.0][MIG] <module>: Migration to 16.0.

Troubleshooting

Sometimes, when performing these operations, the process can hang due to conflicts on the patches being applied. One of the possible problems is because a patch removes entirely a file and git am is not able to resolve this. It ends with a message error: ...: patch does not apply.

If that's your case, you can add --ignore-whitespace at the end of the git am command for allowing the patch to be applied, although there will be still conflicts to be solved, but they will be doable through standard conflict resolution system. Starting from the previous situation, you will need to do:

git am --abort
git format-patch --keep-subject --stdout origin/16.0..origin/15.0 -- <module path> | git am -3 --keep --ignore-whitespace
# resolve conflicts (for example git rm <file>)
git add --all
git am --continue