diff --git a/docsource/010_introduction.rst b/docsource/010_introduction.rst index f763527629d..50f613f1c84 100644 --- a/docsource/010_introduction.rst +++ b/docsource/010_introduction.rst @@ -30,7 +30,7 @@ and that the OpenUpgrade logo includes the ant present in the *OpenERP* logo. Migration from one version to the next -------------------------------------- -In the following, **Openupgrade X** will be understood as the tool used +In the following, **OpenUpgrade X** will be understood as the tool used to migrate a database **from version X-1 to version X**. For example, if you want to migrate from version 14.0 to 15.0: @@ -46,17 +46,17 @@ should perform two Upgrades via OpenUpgrade 15.0, then OpenUpgrade 16.0: .. image:: images/migration-14-16.png -Openupgrade design +OpenUpgrade design ------------------ -* From Openupgrade 5.0 to Openupgrade 13.0, the branches +* From OpenUpgrade 5.0 to OpenUpgrade 13.0, the branches in https://github.com/OCA/OpenUpgrade contain copies (or forks in Git terminology) of the Odoo main project, but with extra commits that include the framework, and the analysis and the migration scripts for each module. -* Since Openupgrade 14.0, the branches contain +* Since OpenUpgrade 14.0, the branches contain - * a module ``openupgrade_framework`` which brings together all the patches of odoo + * a module ``openupgrade_framework`` which brings together all the patches of Odoo * a module named ``openupgrade_scripts`` which contains analysis and migration scripts. Why migrate to a more recent major version @@ -91,7 +91,7 @@ In short, not migrating your Odoo instance to a recent version means increasing For more information, see `OCA presentations `_ on the benefits of migration and how to manage upgrades. -Alternative to Openupgrade +Alternative to OpenUpgrade -------------------------- To migrate from one major version to another, there are alternatives to using OpenUpgrade : diff --git a/docsource/020_required_knowledge.rst b/docsource/020_required_knowledge.rst index f93530d6930..550c3b12317 100644 --- a/docsource/020_required_knowledge.rst +++ b/docsource/020_required_knowledge.rst @@ -1,13 +1,13 @@ Required Knowledge ================== -To Use Openupgrade +To Use OpenUpgrade ------------------ * you should be able to launch an instance of Odoo on your local PC, or on your server, **for each version of your migration**. * You should know how to get `openupgradelib`, obtained from the source repository, installed in your Python environment that is going to run the instance. -* You should know how to invoke the odoo executable, injecting arguments for loading server wide modules and migrations path. +* You should know how to invoke the Odoo executable, injecting arguments for loading server wide modules and migrations path. For example, if you're migrating from version 12.0 to 16.0, you should be able to launch Odoo versions 13.0, 14.0, 15.0 and 16.0. @@ -17,7 +17,7 @@ To Use Openupgrade In this case, using the `gitaggregate `_ tool greatly facilitates the management of these numerous pull requests. -To develop Openupgrade Scripts +To develop OpenUpgrade Scripts ------------------------------ - If you want to develop migration scripts for a given module, you need to have diff --git a/docsource/070_migration_files.rst b/docsource/070_migration_files.rst index 5c033f58c3a..5d2788b9670 100644 --- a/docsource/070_migration_files.rst +++ b/docsource/070_migration_files.rst @@ -1,7 +1,7 @@ Migration Files =============== -For each odoo module, a **migration directory** contains the analysis of +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. @@ -94,9 +94,9 @@ 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 + 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). + 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. diff --git a/docsource/080_migration_script_development.rst b/docsource/080_migration_script_development.rst index 0e435f39dc9..e84f7126325 100644 --- a/docsource/080_migration_script_development.rst +++ b/docsource/080_migration_script_development.rst @@ -98,7 +98,7 @@ Basically, this is the happening during the step when you try to run the upgrade 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 + easy to do through the database manager of your old Odoo `http://localhost:8069/web/database/manager` - [B] run ``odoo -d db-upgrade -u all --stop-after-init`` - [C] In case of error, fix the error adding or editing migration diff --git a/docsource/090_contribute.rst b/docsource/090_contribute.rst index 926ffce1aba..6b1f2c7d684 100644 --- a/docsource/090_contribute.rst +++ b/docsource/090_contribute.rst @@ -58,8 +58,35 @@ For example, the sale_stock migration script may fail, if the stock migration sc * ``TODO``: This shouldn't be usually done. **Note:** -You can reorder lines and group them together for including all of them in a "logical" block for putting only one comment. -Examples: all the noupdate=0 new and del ir* records, or the NEW and DEL lines for a field that is renamed. +Place each marker **inline, on its own line, immediately following the +specific analysis line it annotates**. Don't consolidate multiple adjacent +analysis lines under a single grouped comment, even when the lines are +conceptually related — each gets its own one-line marker. + +Empty section headers (e.g. ``---Models in module 'X'---`` with no +analysis lines below) get **no** marker — leave them blank. Only +sections with content are annotated; a whole module with nothing to do +is recorded in the coverage matrix (column 2), not by marking an empty +work-file section. + +Markers are terse — typically ``# DONE: `` or +``# NOTHING TO DO``. The "why" belongs in the commit message body or +PR description, not in the work file. + +Example: + +.. code-block:: text + + ---Fields in module 'X'--- + X / account.tax / l10n_in_is_lut (boolean): NEW + # DONE: add_fields in pre-migration. + X / account.tax / l10n_in_tax_type (selection): is now stored + # DONE: add_fields in pre-migration; map_values for legacy selection set. + X / res.partner / l10n_in_pan (char): DEL + # NOTHING TO DO: new field name differs; update_db preserves old column as legacy. + + ---XML records in module 'X'--- + # NOTHING TO DO * Write ``pre-migration.py`` and / or ``post-migration.py`` scripts in the same folder. @@ -77,19 +104,26 @@ Examples: all the noupdate=0 new and del ir* records, or the NEW and DEL lines f .. code-block:: shell git add . - git commit -am "[ADD] account" + git commit -am "[MIG] account" git push MY_REMOTE 16.0-mig-account **Note:** - * For a fix of an existing migration scripts, use ``[FIX]`` + * For a first-pass migration script for a module version, use ``[MIG]``. + This is the dominant prefix on recent branches (e.g. ``[MIG] account``, + ``[MIG] hr_recruitment``). + + * For a fix of an existing migration script, use ``[FIX]``. - * For an improvement of an existing migration scripts, use ``[IMP]`` + * For an improvement of an existing migration script, use ``[IMP]``. - * For old versions when OpenUpgrade was a fork (in V13 and before), - use "[OU-ADD]" / "[OU-FIX]" and "[OU-IMP]" to distinguish Odoo team commits - and Openupgraders commits. + * For changes to the OpenUpgrade framework, infrastructure, or + cross-cutting helpers (rather than a per-module migration script), + use ``[OU-ADD]`` / ``[OU-FIX]`` / ``[OU-IMP]``. These prefixes + originated in the V13-and-earlier era when OpenUpgrade shipped + patched copies of Odoo source files, and they remain in use today + for framework-level changes. * Propose your changes to the community for review, opening a Pull Request on github.