From b8af9b2121f51361f6f5e5a1d1d6b13e1d0102bb Mon Sep 17 00:00:00 2001
From: Jocelyn Delalande <jocelyn@crapouillou.net>
Date: Sun, 26 Jul 2020 19:42:49 +0200
Subject: [PATCH] Document how to switch python version for 5.x

Focus is on rebuilding venv (which are bound to a specific python minor
version).

Ref #483
Ref #571
---
 docs/installation.rst |  2 ++
 docs/upgrade.rst      | 31 +++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/docs/installation.rst b/docs/installation.rst
index ca2b9bdf7..4d37af825 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,3 +1,5 @@
+.. _installation:
+
 Installation
 ############
 
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
index 39519b5dc..560c2a975 100644
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -35,6 +35,37 @@ Version-specific instructions
 When upgrading from a major version to another, you **must** follow special
 instructions:
 
+4.x → 5.x
+---------
+
+Switch to a supported version of Python
++++++++++++++++++++++++++++++++++++++++
+
+.. note:: If you are already using Python ≥ 3.6, you can skip this section, no
+          special action is required.
+
+If you were running IHateMoney using Python < 3.6, you must, **before** upgrading:
+
+1. Ensure to have a Python ≥ 3.6 available on your system
+2. Rebuild your virtualenv (if any). It will *not* alter your database nor configuration. For example, if your virtualenv is in `/home/john/ihatemoney/`::
+
+     rm -rf /home/john/ihatemoney
+     pyhton3 -m venv /home/john/ihatemoney
+     source /home/john/ihatemoney/bin/activate
+
+  You might need to ``pip install`` additional dependencies if you are using one
+  or several of the following deployment options :
+
+  - Gunicorn (Nginx)
+  - MySQL
+  - PostgreSQL
+
+If so, pick the ``pip`` commands to use in the relevant section(s) of
+:ref:`installation`.
+
+Then follow :ref:`general-procedure` from step 1. in order to complete the update.
+
+
 2.x → 3.x
 ---------