From f630b2a72e9bbe14666cccf20b84656df30f7574 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 12:13:48 +0200 Subject: [PATCH 01/19] [REM] remove a sentence that says in the introduction, to go to the section 'execute the migration', because there are too many issues in OpenUpgrade on trivial questions, from people who have not read the introduction --- docsource/index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docsource/index.rst b/docsource/index.rst index a178afd991eb..96a056b73ac9 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -9,8 +9,6 @@ Welcome to OpenUpgrade's documentation! +++++++++++++++++++++++++++++++++++++++ -**If you just want to migrate your database and don't care about the technical details, refer to** :doc:`migration_details` - Contents: .. toctree:: From 8f68678a6555585170e84b7f04d7d98aae1859b6 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 12:21:10 +0200 Subject: [PATCH 02/19] [REF] rename intro.rst. (Fist section of the documentation) --- docsource/{intro.rst => 010_introduction.rst} | 0 docsource/index.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docsource/{intro.rst => 010_introduction.rst} (100%) diff --git a/docsource/intro.rst b/docsource/010_introduction.rst similarity index 100% rename from docsource/intro.rst rename to docsource/010_introduction.rst diff --git a/docsource/index.rst b/docsource/index.rst index 96a056b73ac9..e58b0ac962cd 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -14,7 +14,7 @@ Contents: .. toctree:: :maxdepth: 3 - intro.rst + 010_introduction.rst migrating_database.rst community.rst status.rst From a1ac9ea9c8db565a44d2211fd8c9c1403fc96ce3 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 14:37:47 +0200 Subject: [PATCH 03/19] [REF] Add placeholder for the section 'Required Knowledge'. Second main section of the documentation --- docsource/020_required_knowledge.rst | 4 ++++ docsource/index.rst | 1 + 2 files changed, 5 insertions(+) create mode 100644 docsource/020_required_knowledge.rst diff --git a/docsource/020_required_knowledge.rst b/docsource/020_required_knowledge.rst new file mode 100644 index 000000000000..270b68734c3d --- /dev/null +++ b/docsource/020_required_knowledge.rst @@ -0,0 +1,4 @@ +Required Knowledge +================== + +TODO : write here prerequisites. \ No newline at end of file diff --git a/docsource/index.rst b/docsource/index.rst index e58b0ac962cd..2f67f8364bf1 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -15,6 +15,7 @@ Contents: :maxdepth: 3 010_introduction.rst + 020_required_knowledge.rst migrating_database.rst community.rst status.rst From aa2186a4551d8182a8cbce6e056fa44120ec97d5 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 15:08:08 +0200 Subject: [PATCH 04/19] [REF] Rename 'status' into 'Coverage Analysis'. (Third main section of the documentation) --- docsource/{status.rst => 030_coverage_analysis.rst} | 4 ++-- docsource/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename docsource/{status.rst => 030_coverage_analysis.rst} (93%) diff --git a/docsource/status.rst b/docsource/030_coverage_analysis.rst similarity index 93% rename from docsource/status.rst rename to docsource/030_coverage_analysis.rst index ac07d24ec21e..d4531147db36 100644 --- a/docsource/status.rst +++ b/docsource/030_coverage_analysis.rst @@ -1,5 +1,5 @@ -Module coverage -=============== +Coverage Analysis +================= For all official addons, migration scripts should be provided for migrating between subsequent major releases of Odoo. This is the goal of the project. diff --git a/docsource/index.rst b/docsource/index.rst index 2f67f8364bf1..281d31ac2263 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -16,9 +16,9 @@ Contents: 010_introduction.rst 020_required_knowledge.rst + 030_coverage_analysis.rst migrating_database.rst community.rst - status.rst analysis.rst development.rst From 5370d06cc6f96972a9080f71156c3adb4d53c4ab Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 15:32:01 +0200 Subject: [PATCH 05/19] [REF] coverage_analysis part : create subfolder for all the related files --- .gitignore | 2 +- build_openupgrade_docs | 3 ++- docsource/030_coverage_analysis.rst | 24 +++++++++--------- .../coverage_legend.rst | 0 .../images/deleted.png | Bin .../{ => coverage_analysis}/images/new.png | Bin docsource/migration_details.rst | 2 +- 7 files changed, 16 insertions(+), 15 deletions(-) rename docsource/{ => coverage_analysis}/coverage_legend.rst (100%) rename docsource/{ => coverage_analysis}/images/deleted.png (100%) rename docsource/{ => coverage_analysis}/images/new.png (100%) diff --git a/.gitignore b/.gitignore index 479fd54c4654..1ff962a9183b 100644 --- a/.gitignore +++ b/.gitignore @@ -68,7 +68,7 @@ coverage.xml # Sphinx documentation docs/_build/ docs/.doctrees -docsource/modules*-*.rst +docsource/coverage_analysis/modules*-*.rst # Backup files *~ diff --git a/build_openupgrade_docs b/build_openupgrade_docs index 2067305a6a55..2dda8413042c 100755 --- a/build_openupgrade_docs +++ b/build_openupgrade_docs @@ -2,6 +2,7 @@ OUTPUT_DIR=$(realpath $(dirname $0)/./docs) SOURCE_DIR=$(realpath $(dirname $0)/./docsource) +COVERAGE_DIR=$(realpath $(dirname $0)/./docsource/coverage_analysis) BASE_URL=https://raw.githubusercontent.com/OCA/OpenUpgrade/ DOC_PARTS="7.0/openerp/openupgrade/doc/source/modules50-60.rst @@ -23,7 +24,7 @@ for line in $DOC_PARTS; do continue fi name=$(basename $line) - wget -q $BASE_URL/$line -O $SOURCE_DIR/$name + wget -q $BASE_URL/$line -O $COVERAGE_DIR/$name done mkdir -p $OUTPUT_DIR/source/.static diff --git a/docsource/030_coverage_analysis.rst b/docsource/030_coverage_analysis.rst index d4531147db36..5200449d374c 100644 --- a/docsource/030_coverage_analysis.rst +++ b/docsource/030_coverage_analysis.rst @@ -9,15 +9,15 @@ developing parties. See below for an overview of module coverage per version. .. toctree:: :maxdepth: 1 - modules150-160 - modules140-150 - modules130-140 - modules120-130 - modules110-120 - modules100-110 - modules90-100 - modules80-90 - modules70-80 - modules61-70 - modules60-61 - modules50-60 + coverage_analysis/modules150-160 + coverage_analysis/modules140-150 + coverage_analysis/modules130-140 + coverage_analysis/modules120-130 + coverage_analysis/modules110-120 + coverage_analysis/modules100-110 + coverage_analysis/modules90-100 + coverage_analysis/modules80-90 + coverage_analysis/modules70-80 + coverage_analysis/modules61-70 + coverage_analysis/modules60-61 + coverage_analysis/modules50-60 diff --git a/docsource/coverage_legend.rst b/docsource/coverage_analysis/coverage_legend.rst similarity index 100% rename from docsource/coverage_legend.rst rename to docsource/coverage_analysis/coverage_legend.rst diff --git a/docsource/images/deleted.png b/docsource/coverage_analysis/images/deleted.png similarity index 100% rename from docsource/images/deleted.png rename to docsource/coverage_analysis/images/deleted.png diff --git a/docsource/images/new.png b/docsource/coverage_analysis/images/new.png similarity index 100% rename from docsource/images/new.png rename to docsource/coverage_analysis/images/new.png diff --git a/docsource/migration_details.rst b/docsource/migration_details.rst index 6fd46c850df0..d5fdcac07a71 100644 --- a/docsource/migration_details.rst +++ b/docsource/migration_details.rst @@ -40,7 +40,7 @@ Check if there are migration scripts provided for the set of modules that are installed in your Odoo database. If there are modules for which no migration scripts have been developed yet, your migration may fail or the integrity of your database may be lacking. Check the module coverage in -this documentation under :doc:`status` and refer to the :doc:`development` +this documentation under :doc:`030_coverage_analysis` and refer to the :doc:`development` documentation to add the missing migration scripts. 3. Make a copy of the database to migrate From d496ffcc57c0b668ffed649928ae85e3a66b72db Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 16:41:15 +0200 Subject: [PATCH 06/19] [REF] Move coverage text in the correct part --- docsource/030_coverage_analysis.rst | 6 ++++++ docsource/migration_details.rst | 16 +++------------- 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/docsource/030_coverage_analysis.rst b/docsource/030_coverage_analysis.rst index 5200449d374c..149ee61bfa61 100644 --- a/docsource/030_coverage_analysis.rst +++ b/docsource/030_coverage_analysis.rst @@ -6,6 +6,12 @@ between subsequent major releases of Odoo. This is the goal of the project. The design is such that the effort can be distributed between different developing parties. See below for an overview of module coverage per version. +Check if there are migration scripts provided for the set of modules that +are installed in your Odoo database. If there are modules for which no +migration scripts have been developed yet, your migration may fail or the +integrity of your database may be lacking. +Refer to the :doc:`development` documentation to add the missing migration scripts. + .. toctree:: :maxdepth: 1 diff --git a/docsource/migration_details.rst b/docsource/migration_details.rst index d5fdcac07a71..c31df25d52bb 100644 --- a/docsource/migration_details.rst +++ b/docsource/migration_details.rst @@ -33,23 +33,13 @@ openupgradelib pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib -2. Check coverage of the migration scripts for your installed modules -********************************************************************* - -Check if there are migration scripts provided for the set of modules that -are installed in your Odoo database. If there are modules for which no -migration scripts have been developed yet, your migration may fail or the -integrity of your database may be lacking. Check the module coverage in -this documentation under :doc:`030_coverage_analysis` and refer to the :doc:`development` -documentation to add the missing migration scripts. - -3. Make a copy of the database to migrate +2. Make a copy of the database to migrate ***************************************** Decide which database you are going to upgrade. You absolutely *must* make a backup of your live database before you start this process! -4. Adjust the configuration for Odoo and OpenUpgrade +3. Adjust the configuration for Odoo and OpenUpgrade **************************************************** Edit the configuration files and command line parameters to point to the @@ -90,7 +80,7 @@ file under a header *[openupgrade]* selected for installation (as will their dependencies). Be careful not to introduce a circular dependency using this directive. -5. Run the upgrade, fix data and repeat... +4. Run the upgrade, fix data and repeat... ****************************************** Run the upgrade and check for errors. You will probably learn a lot about From 0c5cc85471c623b6892ba45f8c86bd1e23b15332 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 16:53:00 +0200 Subject: [PATCH 07/19] [REF] split migration_database into 'Run migration' and 'After Migration'. (Part 4 and 5 of the Documentation) --- .../{migration_details.rst => 040_run_migration.rst} | 0 .../{after_migration.rst => 050_after_migration.rst} | 0 docsource/development.rst | 2 +- docsource/index.rst | 3 ++- docsource/migrating_database.rst | 8 -------- docsource/use_cases/value_mapping.rst | 2 +- 6 files changed, 4 insertions(+), 11 deletions(-) rename docsource/{migration_details.rst => 040_run_migration.rst} (100%) rename docsource/{after_migration.rst => 050_after_migration.rst} (100%) delete mode 100644 docsource/migrating_database.rst diff --git a/docsource/migration_details.rst b/docsource/040_run_migration.rst similarity index 100% rename from docsource/migration_details.rst rename to docsource/040_run_migration.rst diff --git a/docsource/after_migration.rst b/docsource/050_after_migration.rst similarity index 100% rename from docsource/after_migration.rst rename to docsource/050_after_migration.rst diff --git a/docsource/development.rst b/docsource/development.rst index 768479e5cfb2..15c9643e0f5e 100644 --- a/docsource/development.rst +++ b/docsource/development.rst @@ -97,7 +97,7 @@ The Trial and error process for the development of your scripts --------------------------------------------------------------- Basically, this is the happening during the step when you try to run the upgrade -described in :doc:`migration_details`: +described in :doc:`040_run_migration`: - [A] get the copy of your database in old version as `db-upgrade`, it is easy to do through the database manager of your old odoo diff --git a/docsource/index.rst b/docsource/index.rst index 281d31ac2263..5a3e2d85cd0f 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -17,7 +17,8 @@ Contents: 010_introduction.rst 020_required_knowledge.rst 030_coverage_analysis.rst - migrating_database.rst + 040_run_migration.rst + 050_after_migration.rst community.rst analysis.rst development.rst diff --git a/docsource/migrating_database.rst b/docsource/migrating_database.rst deleted file mode 100644 index 2aaf8d68cf4f..000000000000 --- a/docsource/migrating_database.rst +++ /dev/null @@ -1,8 +0,0 @@ -Migrating your database -+++++++++++++++++++++++ - -.. toctree:: - :maxdepth: 2 - - migration_details - after_migration diff --git a/docsource/use_cases/value_mapping.rst b/docsource/use_cases/value_mapping.rst index 0a05aa684899..a41ab9f8482b 100644 --- a/docsource/use_cases/value_mapping.rst +++ b/docsource/use_cases/value_mapping.rst @@ -204,4 +204,4 @@ Notes This allows you to check that everything is correct after the migration, and to be used by further dependent modules in their migration scripts. Once this is done, you can delete this data. - (See: :doc:`../after_migration`) \ No newline at end of file + (See: :doc:`../050_after_migration`) \ No newline at end of file From 98e8d8a041954105b000633eb291f906ff5968ed Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 17:28:45 +0200 Subject: [PATCH 08/19] [REM] remove obsolete text that explain how to handle xml_id changes. This use case is now described in a dedicated use_case file --- docsource/xmlids.rst | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/docsource/xmlids.rst b/docsource/xmlids.rst index f552d1b580e1..6d65132fd230 100644 --- a/docsource/xmlids.rst +++ b/docsource/xmlids.rst @@ -18,20 +18,5 @@ the noupdate attribute. Therefore, you can ignore most entries here, such as When XML ids of such record types change, the record will be recreated under the new id, and the old record will be unlinked. -More interesting are data that are defined with the noupdate flag. In general, -you need to cover two cases in your scripts. - -* Renamed XML ids of noupdate records. If a product category, or a res.groups - entry has been renamed, you should pass them to - :meth:`~openupgrade.rename_xmlids` - so that the item in your current database survives the migration in its - original form. If the XML id of a renamed noupdate record is not renamed - this way, the new record will be created in addition to the existing one, - and the existing record will lose its xml id. - -* Modified fields of noupdate records, as collected in the - `noupdate_changes.xml` in the migration analysis directory. When developing - the migration scripts for a particular module, review this file and comment - out any fields that must not be overwritten. If there is any data left that - you want to take, load it from your post migration script using - :meth:`~openupgrade.load_data`. +To manage changes to data defined with the noupdate flag, +please refer to the following use case :doc:`use_cases/xml_id_renaming`. From 0ab03beca08e05b3b7fae89a447d024001fec626 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 17:36:04 +0200 Subject: [PATCH 09/19] [REF] create a new main section 'Odoo Migration Manager'. (Section 6 of the documentation) --- ...migrationmanager.rst => 060_odoo_migration_manager.rst} | 0 docsource/development.rst | 7 ++----- docsource/index.rst | 1 + 3 files changed, 3 insertions(+), 5 deletions(-) rename docsource/{migrationmanager.rst => 060_odoo_migration_manager.rst} (100%) diff --git a/docsource/migrationmanager.rst b/docsource/060_odoo_migration_manager.rst similarity index 100% rename from docsource/migrationmanager.rst rename to docsource/060_odoo_migration_manager.rst diff --git a/docsource/development.rst b/docsource/development.rst index 15c9643e0f5e..9ecd71d748e9 100644 --- a/docsource/development.rst +++ b/docsource/development.rst @@ -4,10 +4,8 @@ Migration script development Overview -------- -The execution of the migration scripts is triggered by the "Migration Manager": -:doc:`migrationmanager`. - -As explained with more detail in the page :doc:`migrationmanager`, the migration scripts +As explained with more detail in the page "Migration Manager" +(:doc:`060_odoo_migration_manager`), the migration scripts of a module are usually the combination of 3 python files (might be less if some steps are not necessary): @@ -138,7 +136,6 @@ Learning resources .. toctree:: :maxdepth: 2 - migrationmanager devfaq You can also refer to the following: diff --git a/docsource/index.rst b/docsource/index.rst index 5a3e2d85cd0f..a74904442f33 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -19,6 +19,7 @@ Contents: 030_coverage_analysis.rst 040_run_migration.rst 050_after_migration.rst + 060_odoo_migration_manager.rst community.rst analysis.rst development.rst From b209c1eaa34615e0ac4f6d829331fa145cc7d952 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Wed, 2 Aug 2023 18:13:27 +0200 Subject: [PATCH 10/19] [REF] Move xml_id section and faq question into main section 'Odoo Migration Manager' --- docsource/060_odoo_migration_manager.rst | 48 +++++++++++++++++++++++- docsource/analysis.rst | 1 - docsource/development.rst | 5 --- docsource/devfaq.rst | 21 ----------- docsource/xmlids.rst | 22 ----------- 5 files changed, 47 insertions(+), 50 deletions(-) delete mode 100644 docsource/devfaq.rst delete mode 100644 docsource/xmlids.rst diff --git a/docsource/060_odoo_migration_manager.rst b/docsource/060_odoo_migration_manager.rst index 958b544dccaa..acf7e0fa34a6 100644 --- a/docsource/060_odoo_migration_manager.rst +++ b/docsource/060_odoo_migration_manager.rst @@ -1,5 +1,5 @@ The Odoo Migration Manager -++++++++++++++++++++++++++ +========================== The core mechanism that OpenUpgrade relies on is the migration manager that is already built into Odoo itself. It is this mechanism that was used by Odoo to @@ -26,3 +26,49 @@ Note that you can use this mechanism for your own custom module's lifecycle outside of the OpenUpgrade context. For that reason, the OpenUpgrade helper methods were collected into the python openupgradelib that you can make available in any Odoo instance using the *pip* tool. + +XML IDs +------- + +The OpenUpgrade analysis files give a representation of the XML IDs that a +module defines, in comparison with the previous release of the module. + +XML IDs which do not occur in the updated version of all installed modules +will be removed automatically by the Odoo server, if they do not have +the noupdate attribute. Therefore, you can ignore most entries here, such as + + * ir.actions.* + * ir.model.fields + * ir.model.access + * ir.model + * ir.ui.* + * res.country* + * res.currency* + +When XML ids of such record types change, the record will be recreated under +the new id, and the old record will be unlinked. + +To manage changes to data defined with the noupdate flag, +please refer to the following use case :doc:`use_cases/xml_id_renaming`. + +FAQ +--- + +How are new dependencies treated by the Odoo migration manager? + New dependencies (like the *edi* module is a new dependency of the + *account* module) will be detected by the upgrade process. The + Odoo server code is slightly modified to loop over this part + of the process to install new dependencies and then return to + upgrading the modules that depend on them, until no more modules + are processed. + +Are migration scripts fired when installing new modules? + Yes. That includes any new dependencies that the new version of any + module might declare. You might want to check for a non true value + of the *version* argument, or (better) make your script robust to + running against a database that it does not apply to, in anticipation + of any unknown unknowns. Also another argument for not running the + OpenUpgrade server in production, even though we both know that you + would never ever do so anyway. Developers are free to corrupt the regular + workings of Odoo if it helps the migration. For instance, from OpenUpgrade + 9.0 on, the workflow engine is disabled during field recomputation. diff --git a/docsource/analysis.rst b/docsource/analysis.rst index 23fc43713a61..37e232cc3310 100644 --- a/docsource/analysis.rst +++ b/docsource/analysis.rst @@ -46,5 +46,4 @@ release of Odoo anymore. :maxdepth: 2 analyse - xmlids format diff --git a/docsource/development.rst b/docsource/development.rst index 9ecd71d748e9..baa52a9561be 100644 --- a/docsource/development.rst +++ b/docsource/development.rst @@ -133,11 +133,6 @@ https://github.com/OCA/OpenUpgrade/pulls?q=is%3Apr+%5BFIX%5D+reset+exception Learning resources ------------------ -.. toctree:: - :maxdepth: 2 - - devfaq - You can also refer to the following: - `OpenUpgrade API `_ diff --git a/docsource/devfaq.rst b/docsource/devfaq.rst deleted file mode 100644 index 7593c61f9673..000000000000 --- a/docsource/devfaq.rst +++ /dev/null @@ -1,21 +0,0 @@ -Development FAQ -+++++++++++++++ - -How are new dependencies treated by the Odoo migration manager? - New dependencies (like the *edi* module is a new dependency of the - *account* module) will be detected by the upgrade process. The - Odoo server code is slightly modified to loop over this part - of the process to install new dependencies and then return to - upgrading the modules that depend on them, until no more modules - are processed. - -Are migration scripts fired when installing new modules? - Yes. That includes any new dependencies that the new version of any - module might declare. You might want to check for a non true value - of the *version* argument, or (better) make your script robust to - running against a database that it does not apply to, in anticipation - of any unknown unknowns. Also another argument for not running the - OpenUpgrade server in production, even though we both know that you - would never ever do so anyway. Developers are free to corrupt the regular - workings of Odoo if it helps the migration. For instance, from OpenUpgrade - 9.0 on, the workflow engine is disabled during field recomputation. diff --git a/docsource/xmlids.rst b/docsource/xmlids.rst deleted file mode 100644 index 6d65132fd230..000000000000 --- a/docsource/xmlids.rst +++ /dev/null @@ -1,22 +0,0 @@ -XML IDs -======== -The OpenUpgrade analysis files give a representation of the XML IDs that a -module defines, in comparison with the previous release of the module. - -XML IDs which do not occur in the updated version of all installed modules -will be removed automatically by the Odoo server, if they do not have -the noupdate attribute. Therefore, you can ignore most entries here, such as - - * ir.actions.* - * ir.model.fields - * ir.model.access - * ir.model - * ir.ui.* - * res.country* - * res.currency* - -When XML ids of such record types change, the record will be recreated under -the new id, and the old record will be unlinked. - -To manage changes to data defined with the noupdate flag, -please refer to the following use case :doc:`use_cases/xml_id_renaming`. From 245a9bdd05c12a047b8982b508535a230c4782af Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 15:15:49 +0100 Subject: [PATCH 11/19] [REF] Rename 'Analysis' into 'Analysis Files', (part seven of the documentation) --- docsource/{analysis.rst => 070_migration_files.rst} | 4 ++-- docsource/development.rst | 2 +- docsource/index.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename docsource/{analysis.rst => 070_migration_files.rst} (98%) diff --git a/docsource/analysis.rst b/docsource/070_migration_files.rst similarity index 98% rename from docsource/analysis.rst rename to docsource/070_migration_files.rst index 37e232cc3310..ebde9419b4eb 100644 --- a/docsource/analysis.rst +++ b/docsource/070_migration_files.rst @@ -1,5 +1,5 @@ -Database analysis -+++++++++++++++++ +Migration Files +=============== Database analysis files are hosted in `scripts` subdirectory of the openupgrade_scripts module directory in the https://github.com/OCA/OpenUpgrade diff --git a/docsource/development.rst b/docsource/development.rst index baa52a9561be..64931860747f 100644 --- a/docsource/development.rst +++ b/docsource/development.rst @@ -74,7 +74,7 @@ Since version 14, the migration scripts are located in: During the review for a given module, you can follow this process: -- Review the analysis (read more in :doc:`analysis`). First the file +- Review the analysis (read more in :doc:`070_migration_files`). First the file `openupgrade_analysis.txt` showing some differences between the 2 versions of the module. Then, `openupgrade_analysis_work.txt` to see what the developer planned to do. diff --git a/docsource/index.rst b/docsource/index.rst index a74904442f33..b2113c8b46bb 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -20,8 +20,8 @@ Contents: 040_run_migration.rst 050_after_migration.rst 060_odoo_migration_manager.rst + 070_migration_files.rst community.rst - analysis.rst development.rst You should find the latest version of this documentation here: ``_ From 89e72652dcd3850dc152eed7744fad9a38075f9b Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 16:45:40 +0100 Subject: [PATCH 12/19] [REF] Migration files : Improve description of the place of the migration directories, and add section for OCA modules --- docsource/070_migration_files.rst | 58 ++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 12 deletions(-) diff --git a/docsource/070_migration_files.rst b/docsource/070_migration_files.rst index ebde9419b4eb..446668761c78 100644 --- a/docsource/070_migration_files.rst +++ b/docsource/070_migration_files.rst @@ -1,24 +1,48 @@ Migration Files =============== -Database analysis files are hosted in `scripts` subdirectory of the +For each odoo module, a **migration directory** contains the analysis of +the differences between the previous version and the current version +and the migration scripts developed to ensure the migration +of this module runs properly. + +For versions 14.0 and higher +---------------------------- + +Migration directories are hosted in `scripts` subdirectory of the openupgrade_scripts module directory in the https://github.com/OCA/OpenUpgrade repository. -You can create a custom set of analysis files on any set of modules between -any two versions of Odoo using the `upgrade_analysis` module that is hosted -in https://github.com/oca/server-tools. +For example, the migration folder for migrating the `account` module +from version 13.0 to version 14.0 is located here : + +https://github.com/OCA/OpenUpgrade/tree/14.0/openupgrade_scripts/scripts/account/ + +For versions 13.0 and below +--------------------------- + +Migration directories are hosted in the `migration` folder of each module +in the forks of Odoo at https://github.com/OCA/OpenUpgrade. + -Earlier versions ----------------- +For example, the migration folder for migrating the `account` module +from version 12.0 to version 13.0 is located here : -In editions earlier than 14.0, the analysis files were hosted in the forks of -Odoo at https://github.com/OCA/OpenUpgrade. The module to create the analysis -was placed in each branch of the OpenUpgrade repository under -odoo/addons/openupgrade_records. +https://github.com/OCA/OpenUpgrade/tree/13.0/addons/account/migrations -Contents --------- +Non official addons +------------------- + +For OCA or custom addons, migration directories are hosted in the `migration` +folder of each module. + +For example, the migration folder for migrating the OCA `account_global_discount` module +from version 12.0 to version 13.0 is located here : + +https://github.com/OCA/account-invoicing/tree/13.0/account_global_discount + +Directory contents +------------------ The contents of the migration directory per module are: @@ -47,3 +71,13 @@ release of Odoo anymore. analyse format + +Generate the difference analysis files +-------------------------------------- + +You can create a custom set of analysis files on any set of modules between +any two versions of Odoo using the `upgrade_analysis` module that is hosted +in https://github.com/oca/server-tools. +(for versions 13.0 or lower, the module is named `openupgrade_records` and is +place in each branch of the OpenUpgrade repository under +`odoo/addons/openupgrade_records` path) From c8273ecb2e087ba0665d0f6f6ead9bd6d5b7f90a Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 16:48:08 +0100 Subject: [PATCH 13/19] [REM] remove section that explain how to use 'upgrade_analysis'. This part should be part of the USAGE.rst file of the given module --- docsource/070_migration_files.rst | 1 - docsource/analyse.rst | 38 ------------------------------- 2 files changed, 39 deletions(-) delete mode 100644 docsource/analyse.rst diff --git a/docsource/070_migration_files.rst b/docsource/070_migration_files.rst index 446668761c78..5ac10c381698 100644 --- a/docsource/070_migration_files.rst +++ b/docsource/070_migration_files.rst @@ -69,7 +69,6 @@ release of Odoo anymore. .. toctree:: :maxdepth: 2 - analyse format Generate the difference analysis files diff --git a/docsource/analyse.rst b/docsource/analyse.rst deleted file mode 100644 index c72f94898090..000000000000 --- a/docsource/analyse.rst +++ /dev/null @@ -1,38 +0,0 @@ -How to run your own analysis -============================ -If you do need to run your own analysis, you need to perform the following -steps. - -* Set up two servers of subsequent Odoo releases. Make the following modules - available: `upgrade_analysis` and `openupgrade_scripts`. - - In the case of a release before 14.0, you need to run the fork from the - corresponding branch in https://github.com/OCA/OpenUpgrade. That fork also - contains `openupgrade_records`. - -* On both instances, install a database without demo data and - install the *upgrade_analysis* module, which is included in the - OpenUpgrade server distribution. This will add a menu - *Upgrade Analysis* to the Settings menu. - -* On both instances, install the modules that you need to write migration - scripts for, or use the *Install Modules* from the *Upgrade Analysis* menu. - -* On both instances: from the analysis menu, start the *Generate Records - Wizard*. - -* On the target instance (this is the more recent version): from the - analysis menu, select the *Comparison Configuration* option and - create a new config to connect to the other instance. In the form view of - this configuration record , start a *New Analysis*. - -The analysis files for each of the modules will be placed in the following -location: - -* In the case of Odoo modules: in the path that is indicated by the - `--upgrade-path` parameter of the Odoo server, or in the `scripts` - folder of the `openupgrade_scripts` module directory if it is available in - your addons path - -* In the case of OCA or custom modules: in the `migrations/` - directory in the module directory itself. From c7b784d84042c91600e45a521695f9119448bf02 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 16:53:46 +0100 Subject: [PATCH 14/19] [REF] Move section that describes the content of the analysis file, in the main 7 section. --- docsource/070_migration_files.rst | 90 +++++++++++++++++++++++++++++-- docsource/format.rst | 88 ------------------------------ 2 files changed, 85 insertions(+), 93 deletions(-) delete mode 100644 docsource/format.rst diff --git a/docsource/070_migration_files.rst b/docsource/070_migration_files.rst index 5ac10c381698..8be00e48b80c 100644 --- a/docsource/070_migration_files.rst +++ b/docsource/070_migration_files.rst @@ -66,11 +66,6 @@ The migration directory of the base module contains an additional file as the analysis records of modules that could not be found in the target release of Odoo anymore. -.. toctree:: - :maxdepth: 2 - - format - Generate the difference analysis files -------------------------------------- @@ -80,3 +75,88 @@ in https://github.com/oca/server-tools. (for versions 13.0 or lower, the module is named `openupgrade_records` and is place in each branch of the OpenUpgrade repository under `odoo/addons/openupgrade_records` path) + +Analysis files description +-------------------------- + +The first section displays models which are added or removed from the database. + +The second section lists the model fields which have been signalled by the +analysis script. Every line lists the following columns: + +module / model / field (field type) : description of the change + +Multiple changes per field are listed on separate lines. +If possible, the old situation is added to the change description (in between +parentheses). + +The change description flags the following types of change: + + * The field is now required. The upgrade script might apply the default for + this field, if it is encoded in the model, or any value that you might see + fit (see the openupgrade library + function :meth:`~openupgrade.set_defaults`). If any empty values remain, + these can be reported by the openupgrade report module (TODO). + If the field is a function field after the upgrade, this changes the cause + for action. See below. + + * A field is now a function or a related field. This might or might not call + for any action of your upgrade script, as the value is now automatically + determined. At the same time, this might cause data loss. An example is + the field employee's manager (hr module), which in Odoo 6 is derived + from the employee's department. + + Without any action in the upgrade script, you will lose the manually + encoded employee hierarchy. + + * A selection field's hardcoded selection changes. You need to audit the + function for any change in possible values and may need to map any + differences you encounter. + + * A selection field's selection is now being filled by a function or has + stopped doing so. You need to audit the function for any change in + possible values and may need to map any differences you encounter. + + (Of course, a selection function could change the set of posible values + in between functions.) + + * The field changes type. This always calls for action in your upgrade + script. Rename the database column to a temporary name in the pre script, + then migrate the values in the post script. A typical instance of this + change is when the field becomes a many2one lookup table, or the other way + around. An example of these are the partner's function which became a char + field in Odoo 6, and the partner's title which as a selection (thus + char type database column) and had to be migrated to a many2one on + res.partner.title. + + * A relation field's relation changes. You need to migrate the one target + model to the other, and update the references to them + + * A field is deleted from the model (marked by 'DEL'). Also fields from + deleted models are marked in this way. TODO: mark fields from deleted + models in a distinct manner. Any distinct features of the field are + displayed, for easier manual matching. + You need to audit any new fields + (see below) to see if they correspond to the deleted field and implement + this change in your upgrade script. It might also be the case that a + deleted field is now delegated to a new or existing _inherits table (see below). + + * A field is introduced in the model (marked by 'NEW'). Also fields from + introduced models are marked in this way. TODO: mark fields from introduced + models in a distinct manner? Any distinct features of the field are + displayed, for easier manual matching. You need to audit any deleted + fields (see below) to see if they correspond to the new field and + implement this change in your upgrade script. + + * The _inherits property of a model has changed. It might be the case that + fields which are removed are actually delegated to this newly + inherited table. + + * A new model is introduced. Copy all access data from the access csv and + security rules xml files and load them in your script. Also copy any + other data that may be introduced in this release of Odoo. This may + have consequences for other modules' migration scripts. TODO: create an + overview of new or renamed modules. + +The final section of the database layout analysis contains a simple report on +the changes that were detected. diff --git a/docsource/format.rst b/docsource/format.rst deleted file mode 100644 index 105baf1a3f7f..000000000000 --- a/docsource/format.rst +++ /dev/null @@ -1,88 +0,0 @@ -Fields analysis format -====================== - -The first section displays models which are removed from the database. -The second section displays models which are added to the database. - -TODO: display which models moved to another module, instead of in the field -analysis? It should also be clear how to install such modules from the upgrade - -The second section lists the model fields which have been signalled by the -analysis script. Every line lists the following columns: - -module / model / field (field type) : description of the change - -Multiple changes per field are listed on separate lines. -If possible, the old situation is added to the change description (in between -parentheses). - -The change description flags the following types of change: - - * The field is now required. The upgrade script might apply the default for - this field, if it is encoded in the model, or any value that you might see - fit (see the openupgrade library - function :meth:`~openupgrade.set_defaults`). If any empty values remain, - these can be reported by the openupgrade report module (TODO). - If the field is a function field after the upgrade, this changes the cause - for action. See below. - - * A field is now a function or a related field. This might or might not call - for any action of your upgrade script, as the value is now automatically - determined. At the same time, this might cause data loss. An example is - the field employee's manager (hr module), which in Odoo 6 is derived - from the employee's department. - - Without any action in the upgrade script, you will lose the manually - encoded employee hierarchy. - - * A selection field's hardcoded selection changes. You need to audit the - function for any change in possible values and may need to map any - differences you encounter. - - * A selection field's selection is now being filled by a function or has - stopped doing so. You need to audit the function for any change in - possible values and may need to map any differences you encounter. - - (Of course, a selection function could change the set of posible values - in between functions.) - - * The field changes type. This always calls for action in your upgrade - script. Rename the database column to a temporary name in the pre script, - then migrate the values in the post script. A typical instance of this - change is when the field becomes a many2one lookup table, or the other way - around. An example of these are the partner's function which became a char - field in Odoo 6, and the partner's title which as a selection (thus - char type database column) and had to be migrated to a many2one on - res.partner.title. - - * A relation field's relation changes. You need to migrate the one target - model to the other, and update the references to them - - * A field is deleted from the model (marked by 'DEL'). Also fields from - deleted models are marked in this way. TODO: mark fields from deleted - models in a distinct manner. Any distinct features of the field are - displayed, for easier manual matching. - You need to audit any new fields - (see below) to see if they correspond to the deleted field and implement - this change in your upgrade script. It might also be the case that a - deleted field is now delegated to a new or existing _inherits table (see below). - - * A field is introduced in the model (marked by 'NEW'). Also fields from - introduced models are marked in this way. TODO: mark fields from introduced - models in a distinct manner? Any distinct features of the field are - displayed, for easier manual matching. You need to audit any deleted - fields (see below) to see if they correspond to the new field and - implement this change in your upgrade script. - - * The _inherits property of a model has changed. It might be the case that - fields which are removed are actually delegated to this newly - inherited table. - - * A new model is introduced. Copy all access data from the access csv and - security rules xml files and load them in your script. Also copy any - other data that may be introduced in this release of Odoo. This may - have consequences for other modules' migration scripts. TODO: create an - overview of new or renamed modules. - -The final section of the database layout analysis contains a simple report on -the changes that were detected. From b7483092a1e8bd597677dcd77284c192420e3f47 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 17:00:13 +0100 Subject: [PATCH 15/19] [REF] Move xml ids section that describe the content of the analysis files, in the correct main section --- docsource/060_odoo_migration_manager.rst | 24 ------------------------ docsource/070_migration_files.rst | 24 ++++++++++++++++++++++++ 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docsource/060_odoo_migration_manager.rst b/docsource/060_odoo_migration_manager.rst index acf7e0fa34a6..0dc7bb349118 100644 --- a/docsource/060_odoo_migration_manager.rst +++ b/docsource/060_odoo_migration_manager.rst @@ -27,30 +27,6 @@ module's lifecycle outside of the OpenUpgrade context. For that reason, the OpenUpgrade helper methods were collected into the python openupgradelib that you can make available in any Odoo instance using the *pip* tool. -XML IDs -------- - -The OpenUpgrade analysis files give a representation of the XML IDs that a -module defines, in comparison with the previous release of the module. - -XML IDs which do not occur in the updated version of all installed modules -will be removed automatically by the Odoo server, if they do not have -the noupdate attribute. Therefore, you can ignore most entries here, such as - - * ir.actions.* - * ir.model.fields - * ir.model.access - * ir.model - * ir.ui.* - * res.country* - * res.currency* - -When XML ids of such record types change, the record will be recreated under -the new id, and the old record will be unlinked. - -To manage changes to data defined with the noupdate flag, -please refer to the following use case :doc:`use_cases/xml_id_renaming`. - FAQ --- diff --git a/docsource/070_migration_files.rst b/docsource/070_migration_files.rst index 8be00e48b80c..cac5d1f75f7f 100644 --- a/docsource/070_migration_files.rst +++ b/docsource/070_migration_files.rst @@ -160,3 +160,27 @@ The change description flags the following types of change: The final section of the database layout analysis contains a simple report on the changes that were detected. + +XML IDs +------- + +The OpenUpgrade analysis files give a representation of the XML IDs that a +module defines, in comparison with the previous release of the module. + +XML IDs which do not occur in the updated version of all installed modules +will be removed automatically by the Odoo server, if they do not have +the noupdate attribute. Therefore, you can ignore most entries here, such as + + * ir.actions.* + * ir.model.fields + * ir.model.access + * ir.model + * ir.ui.* + * res.country* + * res.currency* + +When XML ids of such record types change, the record will be recreated under +the new id, and the old record will be unlinked. + +To manage changes to data defined with the noupdate flag, +please refer to the following use case :doc:`use_cases/xml_id_renaming`. \ No newline at end of file From e3ba4258f022ecd95ed26fb5cba22737f99f2723 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 17:07:13 +0100 Subject: [PATCH 16/19] [REF] rename 'development' into '080_migration_script_development', part 8 of the documentation --- docsource/030_coverage_analysis.rst | 2 +- docsource/040_run_migration.rst | 2 +- .../{development.rst => 080_migration_script_development.rst} | 0 docsource/index.rst | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) rename docsource/{development.rst => 080_migration_script_development.rst} (100%) diff --git a/docsource/030_coverage_analysis.rst b/docsource/030_coverage_analysis.rst index 149ee61bfa61..ff43e1b36e3d 100644 --- a/docsource/030_coverage_analysis.rst +++ b/docsource/030_coverage_analysis.rst @@ -10,7 +10,7 @@ Check if there are migration scripts provided for the set of modules that are installed in your Odoo database. If there are modules for which no migration scripts have been developed yet, your migration may fail or the integrity of your database may be lacking. -Refer to the :doc:`development` documentation to add the missing migration scripts. +Refer to the :doc:`080_migration_script_development` documentation to add the missing migration scripts. .. toctree:: :maxdepth: 1 diff --git a/docsource/040_run_migration.rst b/docsource/040_run_migration.rst index c31df25d52bb..c8e39b6b2262 100644 --- a/docsource/040_run_migration.rst +++ b/docsource/040_run_migration.rst @@ -94,4 +94,4 @@ Write the missing migration scripts At this stage, if some of your modules don't have yet migration scripts, you might need to add them yourself. -Read more about the development of migrations scripts in :doc:`development` +Read more about the development of migrations scripts in :doc:`080_migration_script_development` diff --git a/docsource/development.rst b/docsource/080_migration_script_development.rst similarity index 100% rename from docsource/development.rst rename to docsource/080_migration_script_development.rst diff --git a/docsource/index.rst b/docsource/index.rst index b2113c8b46bb..fb5b1c6c33ff 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -21,8 +21,8 @@ Contents: 050_after_migration.rst 060_odoo_migration_manager.rst 070_migration_files.rst + 080_migration_script_development.rst community.rst - development.rst You should find the latest version of this documentation here: ``_ From 4802a208a09f2b5364cad5097815e9a510512b8b Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 17:11:27 +0100 Subject: [PATCH 17/19] [REF] rename 'community' section into '090_contribute' section. 9 and last part of the documentation --- docsource/{community.rst => 090_contribute.rst} | 0 docsource/index.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docsource/{community.rst => 090_contribute.rst} (100%) diff --git a/docsource/community.rst b/docsource/090_contribute.rst similarity index 100% rename from docsource/community.rst rename to docsource/090_contribute.rst diff --git a/docsource/index.rst b/docsource/index.rst index fb5b1c6c33ff..7cc0a9b7a2a3 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -22,7 +22,7 @@ Contents: 060_odoo_migration_manager.rst 070_migration_files.rst 080_migration_script_development.rst - community.rst + 090_contribute.rst You should find the latest version of this documentation here: ``_ From 828d16dfeaa09b836c0e571e2e1e7d4a420051e8 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 17:12:51 +0100 Subject: [PATCH 18/19] [REF] 'contribute' section : set main information at the beginning of the section --- docsource/090_contribute.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docsource/090_contribute.rst b/docsource/090_contribute.rst index 862e92415152..e0037433e7d3 100644 --- a/docsource/090_contribute.rst +++ b/docsource/090_contribute.rst @@ -1,5 +1,17 @@ +Contribute +========== + +In order to contribute to the OpenUpgrade project, please + +* Post your code contributions as pull requests on + https://github.com/OCA/OpenUpgrade +* Donate to the Odoo Community Association (https://github.com/sponsors/OCA) +* Hire any active contributor to this project to help you migrate your + database, and give back any code improvements developed during the project. + + Community involvement -===================== +--------------------- Writing migration scripts for Odoo is a lot of work, that can not be accomplished by a single party. We need your help. @@ -29,12 +41,3 @@ to upgrade a copy of your database and give us feedback. Thank you! -Contribute ----------- -In order to contribute to the OpenUpgrade project, please - -* Post your code contributions as pull requests on - https://github.com/OCA/OpenUpgrade -* Donate to the Odoo Community Association (https://github.com/sponsors/OCA) -* Hire any active contributor to this project to help you migrate your - database, and give back any code improvements developed during the project. From 3a40e7113f919ada6c4cd8d8ca37edbf6ccd2f41 Mon Sep 17 00:00:00 2001 From: Sylvain LE GAL Date: Sun, 5 Nov 2023 17:26:12 +0100 Subject: [PATCH 19/19] [IMP] reduce maxdepth in indexes, to improve readability --- docsource/080_migration_script_development.rst | 2 +- docsource/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docsource/080_migration_script_development.rst b/docsource/080_migration_script_development.rst index 64931860747f..f6a142eb16ad 100644 --- a/docsource/080_migration_script_development.rst +++ b/docsource/080_migration_script_development.rst @@ -49,7 +49,7 @@ Learn from typical Use cases ---------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 use_cases/field_fast_precomputation use_cases/field_renaming diff --git a/docsource/index.rst b/docsource/index.rst index 7cc0a9b7a2a3..54c40dde8237 100644 --- a/docsource/index.rst +++ b/docsource/index.rst @@ -12,7 +12,7 @@ Welcome to OpenUpgrade's documentation! Contents: .. toctree:: - :maxdepth: 3 + :maxdepth: 2 010_introduction.rst 020_required_knowledge.rst