adjust docs for new updater script

1 files changed, 72 insertions, 3 deletions

diff --git a/doc/administration/upgrading.rst b/doc/administration/upgrading.rst
index 4bdc656..9d19f90 100644
--- a/doc/administration/upgrading.rst
+++ b/doc/administration/upgrading.rst
@@ -53,15 +53,84 @@ Upgrading the Database
    is your last chance.
 
 Some updates might change the database schema. Those updates come with database
-migrations that can adapt an existing database to the new schema. In order to
-do so, use ``alembic``:
+migrations that can adapt an existing database to the new schema. In addition
+to database migrations, some updates also modify the on-disk data that
+Fietsboek stores.
+
+Fietsboek comes with a handy tool that allows you to run the right database and
+file migrations: ``fietsupdate``.
+
+You can use the following command to upgrade to the latest installed version:
 
 .. code:: bash
 
-    .venv/bin/alembic -c production.ini upgrade head
+    .venv/bin/fietsupdate update -c production.ini
+
+Or you can view the status of your installation:
+
+.. code:: bash
+
+    .venv/bin/fietsupdate status -c production.ini
+
+.. note::
+
+    The ``fietsupdate`` tool is only there to run database migrations and other
+    update tasks. It does *not* retrieve or install the correct code, please
+    see the above sections to do that.
 
 Restarting Fietsboek
 --------------------
 
 You can now run Fietsboek again. This step depends on the method that you use
 to deploy Fietsboek.
+
+Downgrading
+===========
+
+In some cases, it might be required that you uninstall an update to Fietsboek,
+for example if it introduced a bug. Downgrading is possible and generally
+consists of two steps:
+
+1) Restore the old data format (backwards migration)
+2) Restore the old code
+
+.. warning::
+
+    As with updates, make sure you have backups of your important data ready!
+
+Restoring Data: Backups
+-----------------------
+
+The preferred way to use the old data is by restoring a backup, see
+:doc:`backup`. This method ensures that your data is original and prevents the
+upgrade/downgrade process from inducing errors.
+
+Restoring Data: Downgrading
+---------------------------
+
+If you do not have old backups of your data, you can use ``fietsupdate`` to
+convert your data from the new format to the old one. Please note that the
+upgrade process can not always be undone: If an update deletes data, even the
+downgrade cannot fix it. In such cases, the only way to restore the data is
+through a backup.
+
+To use ``fietsupdate`` to downgrade your data, run the following command,
+replacing ``VERSION`` with the version you want to downgrade to:
+
+.. code:: bash
+
+    .venv/bin/fietsupdate downgrade -c production.ini VERSION
+
+Restoring Code
+--------------
+
+Now that the data has been restored to the old state, you need to restore the
+Fietsboek code to the old version. This works similarly to the update, with the
+difference that you should download and install the version of Fietsboek that
+you downgraded your data to.
+
+If you use ``git``, you can check out old versions of the code by using ``git
+checkout``.
+
+After obtaining the old code, don't forget to install it into your virtual
+environment!