[DOC] contribution guide: clarify prefixes, work-file annotations, brand consistency

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 <https://www.youtube.com/watch?v=WF-BaukCGPs&list=PLRaJ_rIFxm3t6nLStE89Selv597xgvybW>`_ 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 :

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 <https://pypi.org/project/git-aggregator>`_
   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

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.
 

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

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: <one-line summary>`` 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.