# HG changeset patch
# User Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
# Date 2019-03-10 19:58:28
# Node ID de92f48c13757e9f836358e650489bf2d6278750
# Parent  08de75df77755ffd7b01a6fe3fafe6f7c1ec1902

docs: suggest creating a new virtual environment for major upgrades

While not strictly necessary, it may be interesting to start from a new
virtualenv rather than upgrading inside the old one. This will remove old
packages once installed manually but no longer necessary. At the same time,
it makes a rollback of the upgrade process more easy.

Update the upgrade instructions to this effect.

diff --git a/docs/upgrade.rst b/docs/upgrade.rst
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -59,17 +59,30 @@ database type, settings, location, etc. 
 older, this was ``sqlalchemy.db1.url``.
 
 
-3. Activate the Kallithea virtual environment (if any)
-------------------------------------------------------
+3. Activate or recreate the Kallithea virtual environment (if any)
+------------------------------------------------------------------
+
+.. note::
+    If you did not install Kallithea in a virtual environment, skip this step.
 
-Verify that you are using the Python environment that you originally
-installed Kallithea in by running::
+For major upgrades, e.g. from 0.3.x to 0.4.x, it is recommended to create a new
+virtual environment, rather than reusing the old. For minor upgrades, e.g.
+within the 0.4.x range, this is not really necessary (but equally fine).
+
+To create a new virtual environment, please refer to the appropriate
+installation page for details. After creating and activating the new virtual
+environment, proceed with the rest of the upgrade process starting from the next
+section.
+
+To reuse the same virtual environment, first activate it, then verify that you
+are using the correct environment by running::
 
     pip freeze
 
 This will list all packages installed in the current environment. If
-Kallithea isn't listed, activate the correct virtual environment.
-See the appropriate installation page for details.
+Kallithea isn't listed, deactivate the environment and then activate the correct
+one, or recreate a new environment. See the appropriate installation page for
+details.
 
 
 4. Install new version of Kallithea