Add docs on packages in TLJH

docs/contributing/packages.rst

@@ -0,0 +1,48 @@
+.. _contributing/packages:
+
+=======================
+Environments & Packages
+=======================
+
+TLJH installs packages from different sources during installation.
+This document describes the various sources and how to upgrade
+versions of packages installed.
+
+Python Environments
+===================
+
+TLJH sets up two python environments during installation.
+
+1. **Hub Environment**. JupyterHub, authenticators, spawners, TLJH plugins
+   and the TLJH configuration management code is installed into this
+   environment. A `venv <https://docs.python.org/3/library/venv.html>`_ is used,
+   primarily since conda does not support ARM CPUs and we'd like to support the
+   RaspberryPI someday. Admins generally do not install custom packages
+   in this environment.
+
+2. **User Environment**. Jupyter Notebook, JupyterLab, nteract, kernels,
+   and packages the users wanna use (such as numpy, scipy, etc) are installed
+   here. A `conda <https://conda.io>`_ environment is used here, since
+   a lot of scientific packages are available from Conda. ``pip`` is still
+   used to install Jupyter specific packages, primarily because most notebook
+   extensions are still available only on `PyPI <https://pypi.org>`_.
+   Admins can install packages here for use by all users.
+
+Python package versions
+=======================
+
+In ``installer.py``, most Python packages have a version specified. This
+can be upgraded freely whenever needed. Some of them have version checks
+in ``integration-tests/test_extensions.py``, so those might need
+updating too.
+
+Apt packages
+============
+
+Base operating system packages, including Python itself, are installed
+via ``apt`` from the base Ubuntu repositories. The one exception to this
+is nodejs, which is installed from the `nodesource <https://github.com/nodesource/distributions>`_
+apt repository. The Ubuntu provided version of nodejs is usually too old.
+
+We generally do not pin versions of packages provided by apt, instead
+just using the latest versions provided by Ubuntu.