From e6d340eb449a7fc5b083330083810ee2919cb12e Mon Sep 17 00:00:00 2001
From: GeorgianaElena <georgiana.dolocan@gmail.com>
Date: Thu, 30 Jan 2020 19:50:20 +0200
Subject: [PATCH] Document how to upgrade python for existing installs

---
 docs/howto/env/user-environment.rst | 54 +++++++++++++++++++++++++++++
 docs/install/index.rst              |  2 ++
 2 files changed, 56 insertions(+)

diff --git a/docs/howto/env/user-environment.rst b/docs/howto/env/user-environment.rst
index c46b08c..66c0144 100644
--- a/docs/howto/env/user-environment.rst
+++ b/docs/howto/env/user-environment.rst
@@ -153,3 +153,57 @@ The most common & portable way to fix this when using ``ssh`` is:
 .. code-block:: bash
 
    sudo PATH=${PATH} conda install -c conda-forge gdal
+
+
+Upgrade to a newer Python version
+=================================
+
+All new TLJH installs use miniconda 4.7.10, which comes with a Python 3.7
+environment for the users. The previously TLJH installs came with miniconda 4.5.4,
+which meant a Python 3.6 environment.
+
+To upgrade the Python version of the user environment, one can:
+
+*  **Start fresh on a machine that doesn't have TLJH already installed.**
+
+   See the :ref:`installation guide <install/installing>` section about how to install TLJH.
+
+*  **Upgrade Python manually.**
+
+   Because upgrading Python for existing installs can break packages alaredy installed
+   under the old Python, upgrading your current TLJH installation, will NOT upgrade
+   the Python version of the user environment, but you may do so manually.
+
+   **Steps:**
+
+   1. Activate the user environment, if using ssh.
+      If the terminal was started with JupyterHub, this step can be skipped:
+
+      .. code-block:: console
+
+         source /opt/tljh/user/bin/activate
+
+   2. Get the list of currently installed pip packages (so you can later install them under the
+      new Python):
+
+      .. code-block:: console
+
+         pip freeze > pip_pkgs.txt
+
+   3. Update all conda installed packages in the environment:
+
+      .. code-block:: console
+
+         sudo conda update --all
+
+   4. Update Python version:
+
+      .. code-block:: console
+
+         conda install python=3.7
+
+   5. Install the pip packages previously saved:
+
+      .. code-block:: console
+
+         pip install pip_pkgs.txt
diff --git a/docs/install/index.rst b/docs/install/index.rst
index a28baca..b783486 100644
--- a/docs/install/index.rst
+++ b/docs/install/index.rst
@@ -1,3 +1,5 @@
+.. _install/installing:
+
 ==========
 Installing
 ==========