[IMP] install/maintain: update info about upgrade process on Odoo.sh

closes odoo/documentation#2494

Id: 2744270
X-original-commit: 815acb64c4
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
Signed-off-by: Pirlot Donatienne (dopi) <dopi@odoo.com>
Co-authored-by: Stanislas <sts@odoo.com>
Co-authored-by: Donatienne <dopi@odoo.com>

content/administration/odoo_sh/getting_started/branches.rst

@@ -279,10 +279,21 @@ The *import database* feature accepts database archives in the format provided b
 * the Odoo.sh backup download button of this *Backups* tab,
 * the Odoo.sh dump download button in the :ref:`Builds view <odoosh-gettingstarted-builds>`.
 
+.. _odoo_sh/upgrade:
+
+Upgrade
+-------
+
+Available for production and staging branches for valid projects.
+
+.. seealso::
+    :doc:`Upgrade - Odoo.sh <../../upgrade/odoo_sh>`
+
 .. _odoosh-gettingstarted-branches-tabs-settings:
 
 Settings
 --------
+
 Here you can find a couple of settings that only apply to the currently selected branch.
 
 .. image:: branches/interface-branches-settings.jpg
@@ -384,7 +395,7 @@ we are considering the feature if there is enough demand.
 In case the domain of your users email addresses use SPF (Sender Policy Framework) or DKIM
 (DomainKeys Identified Mail), don't forget to authorize Odoo as a sending host in your domain name
 settings to increase the deliverability of your outgoing emails.
-The configuration steps are explained in the documentation about :ref:`SPF 
+The configuration steps are explained in the documentation about :ref:`SPF
 <email_communication/spf_compliant>` and :ref:`DKIM <email_communication/dkim_compliant>`.
 
 

content/administration/upgrade/odoo_sh.rst

@@ -1,66 +1,132 @@
-
 =======
 Odoo.sh
 =======
 
-Test upgrade request
-====================
+.. _upgrade/odoo_sh/overview:
 
-Download a dump of your database (from the :ref:`Builds view
-<odoosh-gettingstarted-builds-download-dump>`), choose the **exact copy** and **without filestore**
-options. Upload the .sql.gz dump on https://upgrade.odoo.com/upload and select the testing purpose.
-Once it's processed, you'll get a dump of the database in return.
+Overview
+========
 
-.. important::
-   To have the most up-to-date test version of your database, create a backup of your production
-   database just before creating your request. Upload it in your staging branch, select **Exact
-   dump** and **Without filestore**, and then click *start*.
-
-Test your upgraded database
-===========================
-
-At the beginning of your upgrade project, make sure that you create a new staging branch for testing
-purposes by forking your main branch.
-
-Once the staging build is complete (it doesn't matter if it failed due to the version
-incompatibility), import your upgraded dump in the *Backups* tab of the branch.
+Odoo.sh is integrated with the upgrade platform to make the upgrade process easier.
 
 .. note::
-   The platform automatically detects the version of the dump and changes the version of Odoo's
-   source code to the corresponding version of the build.
+   The :guilabel:`Upgrade` tab is available in the branches view. It is only available for valid
+   projects with a valid production build.
 
-Test the upgraded database and make sure everything runs as it's supposed to.
+.. image:: odoo_sh/odoo-sh-menu.png
+   :align: center
+   :alt: Click on the upgrade menu
 
-Upgrade your production database
-================================
+The suggested upgrade steps on Odoo.sh are:
 
-Once you've tested everything and you're satisfied, start the process over to get an up-to-date
-upgraded dump:
-
-* Make a new dump of your production database (as described in step 1)
-* Upload it on upgrade.odoo.com and select the Production purpose
-* Receive the newly upgraded dump and import it in your production branch. The build might get
-  marked as failed because the platform will run it with the upgraded databases' Odoo version
-  together with the old custom code.
-* Merge or commit the upgraded custom code in the production branch
-
-If anything goes wrong, remember you can restore a backup. The platform will always make one before
-you make any Odoo.sh operation on the production database. If the restored backup comes from a
-previous version, the platform will detect it and change the project's Odoo version back if it needs
-to.
-
-Custom modules (if applicable)
-==============================
-
-The upgrade of a database that contains custom modules is a 2 step process.
-
-#. The standard upgrade is done when your upgrade request is completed.
-#. Your custom modules also need to be upgraded to keep them compatible with the new version.
-
-Depending on your contract, the upgrade of your custom modules can be done
-- by yourself
-- by your Partner
-- by Odoo (if you hold a subscription to 'Maintenance of Customizations')
+#. On a :guilabel:`Development` branch, upgrade your custom modules to keep them compatible with the
+   new version and thoroughly **test them**.
+#. Switch that branch to the :guilabel:`Staging` branch, **upgrade** the last daily production
+   backup and **test it**. Write upgrade scripts if necessary.
+#. Trigger the production upgrade from your :guilabel:`Production` branch and sit tight.
 
 .. seealso::
-   - :ref:`upgrade/sla`
+   - :doc:`../../administration/upgrade`
+   - :doc:`Upgrade FAQ <../upgrade/faq>`
+   - :doc:`Introduction to Odoo.sh <../odoo_sh/overview/introduction>`
+
+.. _upgrade/odoo_sh/custom-modules:
+
+Upgrade your custom modules
+===========================
+
+The first step is to upgrade your custom modules to keep them compatible with the new version. Fork
+your :guilabel:`Production` branch in the :guilabel:`Development` stage, then go to the settings of
+your :guilabel:`Development` branch and select the Odoo version you target. If needed, modify your
+code to be compatible with the new version. Make sure to **test** your features are still working
+correctly.
+
+.. note::
+   Depending on your contract, the upgrade of your custom modules can be done by yourself, by your
+   Partner or by Odoo (if you hold a subscription including maintenance of customizations).
+
+.. _upgrade/odoo_sh/testing-phase:
+
+Upgrade your database on a staging branch
+=========================================
+
+Take the upgraded development branch and drag & drop it to :guilabel:`Staging`.
+
+Go to the :guilabel:`Upgrade` tab and select the :guilabel:`target version`. Then, click on
+:guilabel:`Test Upgrade`.
+
+.. image:: odoo_sh/odoo-sh-staging.png
+   :align: center
+   :alt: Odoo.sh project and tabs
+
+The **latest production daily automatic backup** is sent to the
+`upgrade platform <https://www.upgrade.odoo.com>`_ to start the upgrade test process.
+
+.. note::
+   You can follow the upgrade process by going to the :guilabel:`Upgrade` menu of your
+   :guilabel:`Production` branch.
+
+When the upgraded backup is ready on the `upgrade platform <https://www.upgrade.odoo.com>`_, it is
+automatically downloaded back to your project.
+
+The branch is now in a **special mode**: each time a **commit is pushed** on the branch, a
+**restore operation** of the upgraded backup occurs, and an **update of all the custom modules**
+happens. This allows you to quickly iterate on your custom modules upgrade scripts. The log file of
+the upgrade process can be found at :file:`~/logs/upgrade.log` in your newly upgraded staging build.
+
+.. note::
+   - The **special upgrade mode** is automatically closed after 30 days.
+   - It may happen that custom modules are no longer needed after an upgrade. Custom modules in the
+     upgraded database are set to be updated. If the modules are missing in the code, the update
+     fails, thus failing the whole process. An empty module with a manifest and possibly some custom
+     upgrade script are necessary to clean up the database. The complete removal of the module has
+     to be handled afterwards.
+
+Functionally test your upgraded database
+========================================
+
+Now that the test upgraded database is available on your staging branch, **thoroughly test it** and
+make sure everything runs as it's supposed to. Once you are satisfied with the result, you are ready
+to upgrade your production database.
+
+Production upgrade
+==================
+
+Once you are happy with your testing, you can start the process on the :guilabel:`Production`
+branch.
+
+On your :guilabel:`Production` branch, go to the :guilabel:`Upgrade` tab, select the
+:guilabel:`targeted version` and click on the :guilabel:`start Upgrade` button.
+
+.. image:: odoo_sh/odoo-sh-prod.png
+   :align: center
+   :alt: View from the upgrade tab
+
+The actual process is **triggered as soon as you push a new commit** in your branch. Make sure you
+are pushing code that is compatible with the new version. For example by merging the code from your
+upgraded staging branch.
+
+.. note::
+   You can see the progress of the upgrade by going to the :guilabel:`Upgrade` tab of the main
+   branch.
+
+.. image:: odoo_sh/odoo-sh-progress.png
+   :align: center
+   :alt: View showing the progress of the upgrade
+
+.. important::
+   Your database is unavailable throughout the process.
+
+.. note::
+   If anything goes wrong, the platform automatically reverts the upgrade, the same as it would be
+   for a regular update. In case of success, a backup is always made.
+
+The update of your custom modules must be successful to complete the entire upgrade process. Make
+sure the status of your staging upgrade is :guilabel:`successful` before trying it in production.
+
+.. note::
+   It may happen that custom modules are no longer needed after an upgrade. Custom modules in the
+   upgraded database are set to be updated. If the modules are missing in the code, the update
+   fails, thus failing the whole process. An empty module with a manifest and possibly some custom
+   upgrade script are necessary to clean up the database. The complete removal of the module has to
+   be handled afterwards.