[ADD] Upgrade documentation: Migration scripts and Util package

[augustoPerez]

Continuation or #6757

In this PR we add more technical information on the Upgrade Process:

• How to write Migration scripts
• How to use the Upgrade Util package

[robodoo]

Pull request status dashboard.

[KangOl]

Please don't call them migration script but upgrade script
The only occurrence of migrate should def migrate.

[aj-fuentes]

I think you should add a section somewhere to describe how to use the upload script (via Python). Upgrade support team answer the same questions again and again in tickets. A recent one: using -i option to upload a pre-made dump. But also the ... restore command to download a previously done request after a disconnect.

[augustoPerez]

Hey @aj-fuentes
Thanks for your comment!

IMO, it could be a good idea to create a "Frequently Asked Questions" page for upgrade where we can answer those kind of questions and how to solve recurrent issues.
I will add it to my tasks, think on a structure for this page and include it in the next upgrade related PR.

Please, if you have any suggestions or ideas on the structure or the questions/topics to include, don't hesitate to let me know

[Feyensv]

Pushed a fixup commit with suggestions/improvements ;)
Feel free to see if everything's ok for you and squash the commits.

[Feyensv]

Phases ? wouldn't steps be more understandable/clear ? 🤔

[AntoineVDV]

For the record, the odoo/upgrade wiki mentions "steps".

[AntoineVDV]

Hello, it's nice to see progress on the documentation of the upgrade-util repo 👍

Content-wise, I think we're good. I have made a few nitpicking comments, but that's it.

However, I think we can come up with a better structure for the new content. Indeed, in the documentation, we try as much as possible to organize the structure according to the type of content: tutorials, how-to guides, and reference pages where it makes sense. It helps keep the information discoverable and allows the user to get to it faster.

Here, the valuable reference on the upgrade-util repository is "buried" inside the "Upgrade a customized database" how-to guide, which not many R&D developers at Odoo will browse out of curiosity. Also, the content of the "Upgrade scripts" page is a mix of how-to instructions (e.g., "create this and that files", "upgrade like this on Odoo.sh") and reference statements (e.g., migrate signature, the structure of the migrations directory, the steps of the upgrade) that is oriented on only the custom module upgrade use-case, while it could be made more generic and also explain how upgrades work on the odoo/upgrade repository.

Please consider making the minor changes below that should help restructure the new content:

1. Move the upgrade_util page to /developer/reference/upgrade_util. I'd say before "External API".
2. Extract the reference-oriented content of the upgrade_scripts page to that new reference page. Namely:
   • The migrate signature.
   • The structure of the migrations directory, with the content rephrased to be statements rather than steps: "The path to the script should be in the format something/something/etc, where: - migrations is that, - <version> is this, etc.
   • The steps of the upgrade, in the same tone as above.
3. Extract the how-to-oriented content of the upgrade_scripts page to the parent "Upgrade a customized database" page. That should be only the "Running and testing upgrade scripts" section.
4. Delete the two pages under upgrade_custom_db.
5. Make a pass on the reference documentation to make sure it is compatible with the "standard upgrade" (odoo/upgrade) flow.

Tell me what you think, or feel free to reach out for a discussion about that ;)

[augustoPerez]

Hello @AntoineVDV ,

Thanks for the comments and suggestions!
I have applied almost all of them

Regarding the missing ones:

• Phases vs Steps of upgrade scripts:
  We used "Steps" when talking about "How to upgrade a customized database" because we consider them as a specific series of actions to follow in order to get a cusotmized database upgraded.
  We refer as "Phases" of upgrade scripts because these are different periods or stages within the upgrade process of Odoo.
• Bulleted list is broken: [ADD] Upgrade documentation: Migration scripts and Util package #7330 (comment)
• Extract the reference-oriented content of the upgrade_scripts:
  The content of this wiki not target for people in R&D, it's meant for customers and partners that are handling their own customization.
  The process for R&D developers includes extra or different steps, suggestions and conventions that are not relevant for customers/partners and will be confusing to them. Those can be found in the odoo upgrade wiki.
  On top of this, I'm not sure it makes sense to make public documentation that refers only to our internal process, as odoo/upgrade is not open source.

[AntoineVDV]

As discussed, let's keep the best of both worlds: whatever is generic enough goes to the reference page; what is specific to custom upgrade stays in the how-to, without a counterpart for the odoo/upgrade repo.

[AntoineVDV]

@robodoo r+