Upgrade steps
=============

A clean upgrade path is needed to keep Quaive installations sane, for
this reason it is required that the checked in code provides the needed
upgrade steps to keep the data in sync with the code.

To help out with the creation and installation of the upgrade steps, we
adopted the package ``collective.ftw.upgrade``.

Developing upgrade steps in the usual way will still work.

Before you start
----------------

1. be sure you have the ``bin/upgrade`` script in your buildout
   directory. If not check
   https://github.com/collective/collective.ftw.upgrade?tab=readme-ov-file#installing-collectiveftwupgrades-console-script.
2. be sure you either have no ``experimental.publishtraverse`` egg in
   your instance or if you have use, set the
   ``EXPERIMENTAL_PUBLISH_TRAVERSE_ONLY_WARN``, e.g.:

::

   EXPERIMENTAL_PUBLISH_TRAVERSE_ONLY_WARN=True ./bin/instance fg

3. Check that package ``collective.ftw.upgrade`` is installed in your site.

Add an upgrade step
-------------------

To add an upgrade step run the ``create`` subcommand:

::

   $ ./bin/upgrade create --path src/ploneintranet/upgrade/v21 "Foo bar"
   Created upgrade step at: /home/.../src/ploneintranet/upgrade/v21/20200608154912_foo_bar

Go to the created folder and edit ``upgrade.py`` to fit your needs.

Add in the folder all the generic setup files that you want to be run in
the upgrade step. E.g. you can add a ``registry.xml`` file that contains
the changes you want to apply to your site.

Check ``./bin/upgrade create --help`` for further details.

List the available upgrade steps
--------------------------------

To list the pending upgrade steps run the ``list`` subcommand.

If not upgrade is pending:

::

   $ ./bin/upgrade list -s Plone -u
   Proposed upgrades:
   ID:  Title:

If an upgrade is pending you will see:

::

   $ ./bin/upgrade list -s Plone -u
   Proposed upgrades:
   ID:                                         Title:
   20200608154912@ploneintranet.suite:default  Foo bar.

Check ``./bin/upgrade list --help`` for further details.

Install the upgrade steps
-------------------------

To install the pending upgrade steps run the ``install`` subcommand.

::

   $ ./bin/upgrade install -s Plone -p
   ... some logging ...
   Result: SUCCESS

Check ``./bin/upgrade install --help`` for further details.
