Skip to content

Migration to version 20.0

Jump to bottom
Pedro M. Baeza edited this page Sep 22, 2026 · 3 revisions

Before migrating

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, nor business methods changes. 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.

Tasks NOT to do in the migration

  • change copyright year

    A line like this:

    # Copyright 2024 ACME Ltd - Johnny Glamour

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

  • change original authors

How-to

Technical method to migrate a module from "19.0" to "20.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 20.0
$ cd $repo
$ git checkout -b 20.0-mig-$module origin/20.0
$ git format-patch --keep-subject --stdout origin/20.0..origin/19.0 -- $module | git am -3 --keep
$ pre-commit run -a  # to run pre-commit linters and formatters (please ignore pylint errors at this stage)
$ git add -A
$ git commit -m "[IMP] $module: pre-commit auto fixes"  --no-verify  # it is important to do all the formatting in one commit the first time
  • On the last step, there may be no changes done by pre-commit, so just ignore the message saying "Nothing to commit".
  • Check https://github.com/OCA/maintainer-tools/wiki/Merge-commits-in-pull-requests for a procedure for reducing commits from "OCA Transbot...".
  • If the module is renamed in the migration, you have to rename the whole commit history. If not done, on the next version, when these commands will be executed again, only the latest commit will be brought. For doing the renaming, execute the following commands: 
    git filter-branch --tree-filter 'if [ -d $module ]; then mv $module $new_module_name; fi' HEAD
git rebase origin/20.0
    or this on newer ones: 
    git filter-repo --path-rename $module/:$new_module_name/ --refs HEAD --force
  • Adapt the module to the 20.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 20.0"
$ git remote add $user_org git@github.com:$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 20.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: [20.0][MIG] <module>: Migration to 20.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/20.0..origin/19.0 -- <module path> | git am -3 --keep --ignore-whitespace
# resolve conflicts (for example git rm <file>)
git add --all
git am --continue

Clone this wiki locally