From 59fc6e0d7883284475623ae148217ab1015d3723 Mon Sep 17 00:00:00 2001
From: Jocelyn Delalande <jocelyn@crapouillou.net>
Date: Thu, 26 Oct 2017 14:19:25 +0200
Subject: [PATCH] Add an upgrade guide

fix #274
---
 CHANGELOG.rst         |  1 +
 docs/index.rst        |  1 +
 docs/installation.rst |  2 ++
 docs/upgrade.rst      | 78 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 82 insertions(+)
 create mode 100644 docs/upgrade.rst

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 2f3a0375..32e4adf3 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -32,6 +32,7 @@ Added
 - ACTIVATE_ADMIN_DASHBOARD setting (#262)
 - Link to the dashboard in the navigation bar (#262)
 - Dockerfile
+- Documentation explaining the upgrade process
 
 Removed
 =======
diff --git a/docs/index.rst b/docs/index.rst
index 8d96058c..40b917ee 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,7 @@ Table of content
    :maxdepth: 1
 
    installation
+   upgrade
    api
    contributing
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 9a0a7a92..9a5bd5a7 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -29,6 +29,8 @@ most small to medium setups.
 
 .. note:: If curious, source config templates can be found in the `project git repository <https://github.com/spiral-project/ihatemoney/tree/master/ihatemoney/conf-templates>`_.
 
+.. _virtualenv-preparation:
+
 Prepare virtualenv (recommended)
 ================================
 
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
new file mode 100644
index 00000000..9e48a98d
--- /dev/null
+++ b/docs/upgrade.rst
@@ -0,0 +1,78 @@
+Upgrading
+#########
+
+We keep `a ChangeLog
+<https://github.com/spiral-project/ihatemoney/blob/master/CHANGELOG.rst>`_. Read
+it before upgrading.
+
+Ihatemoney follows `semantic versioning <http://semver.org/>`_. So minor/patch
+upgrades can be done blindly.
+
+General procedure
+=================
+
+*(sufficient for minor/patch upgrades)*
+
+1. From the virtualenv (if any)::
+
+    pip install -U ihatemoney
+
+2. Restart *supervisor*, or *Apache*, depending on your setup.
+
+You may also want to set new configuration variables (if any). They are
+mentioned in the `ChangeLog
+<https://github.com/spiral-project/ihatemoney/blob/master/CHANGELOG.rst>`_, but
+this is **not required for minor/patch upgrades**, a safe default will be used
+automatically.
+
+Version-specific instructions
+=============================
+
+*(must read for major upgrades)*
+
+When upgrading from a major version to another, you **must** follow special
+instructions:
+
+1.x → 2.x
+---------
+
+Switch from git installation to pip installation
+++++++++++++++++++++++++++++++++++++++++++++++++
+
+The recomended installation method is now using *pip*. Git is now intended for
+development only.
+
+.. warning:: Be extra careful to not remove your sqlite database nor your
+             settings file, if they are stored inside the cloned folder.
+
+1. Delete the cloned folder
+
+
+.. note:: If you are using a virtualenv, then the following commands should be run inside it (see
+          :ref:`virtualenv-preparation`).
+
+
+2. Install ihatemoney with pip::
+
+    pip install ihatemoney
+
+3. Fix your configuration file (paths *have* changed), depending on the software you use in your setup:
+
+   - **gunicorn**: ``ihatemoney generate-config gunicorn.conf.py`` (nothing
+     critical changed, keeping your old config might be fine)
+
+   - **supervisor** : ``ihatemoney generate-config supervisord.conf`` (mind the
+     ``command=`` line)
+
+   - **apache**: ``ihatemoney generate-config apache-vhost.conf`` (mind the
+     ``WSGIDaemonProcess``, ``WSGIScriptAlias`` and ``Alias`` lines)
+4. Restart *Apache* or *Supervisor*, depending on your setup.
+
+Upgrade ADMIN_PASSWORD to its hashed form
+++++++++++++++++++++++++++++++++++++++++++
+
+.. note:: Not required if you are not using the ADMIN_PASSWORD feature.
+
+``ihatemoney generate_password_hash`` will do the hashing job for you, just put
+ its result in the ``ADMIN_PASSWORD`` var from your `ihatemoney.cfg` and
+ restart *apache* or the *supervisor* job.