From a33cbd9d903bc6d0d74e5c64b11d5baed8169e17 Mon Sep 17 00:00:00 2001
From: IAlibay <ialibay@mdanalysis.org>
Date: Tue, 15 Aug 2023 11:20:07 +0100
Subject: [PATCH] Add comments on build isolation use

---
 .github/actions/build-src/action.yaml | 32 ++++++++++++++++++++++++++-
 .github/workflows/gh-ci.yaml          |  3 +++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/.github/actions/build-src/action.yaml b/.github/actions/build-src/action.yaml
index 8c656f8304f..a17d0f15a0c 100644
--- a/.github/actions/build-src/action.yaml
+++ b/.github/actions/build-src/action.yaml
@@ -10,7 +10,37 @@ inputs:
     required: true
     default: false
   isolation:
-    descriptions: 'use build isolation for pip installs'
+    # Details on build isolation can be found here:
+    # https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/#build-isolation
+    #
+    # A short description of how this works in pratice is provided here:
+    # * If build isolation is on, pip will create wheels for MDAnalysis in a
+    #   fully isolated temporary environment hence making sure that build
+    #   requirements are handled independently of the runtime environment
+    #   (whatever is already in your Python PATH at the time of install).
+    #   For example, with build isolation on, you could have an old version
+    #   of NumPy available in your current Python environment, but build with
+    #   a much newer one.
+    # * If build isolation is off (through the --no-build-isolation flag), the
+    #   pip build system depends on what is currently avaiable in your Python
+    #   environment. So if NumPy is necessary and you have a version already
+    #   installed, it will just use that directly. There is a massive potential
+    #   for breaking an environment if misused, so this is very much advised
+    #   only in cases where you know exactly what your enviroment does / has
+    #   (such as the tests we run here).
+    #
+    # In practice we use build isolation in MDAnalysis CI when:
+    # * We are trying to test MDAnalysis with a different / older runtime
+    #   version of a key build dependency (e.g. NumPy).
+    # We don't use build isolation when:
+    # * We know we have already installed the required dependencies earlier
+    #   and we want to make sure that we use those dependnecies for the build
+    #   (e.g. we want to check that the packages we pulled for conda-forge
+    #    work for the build, not the ones from PyPi).
+    # * We want to test the build & runtime with a sepecial version of a
+    #   build dependency that won't get picked up by the pip install. For
+    #   example, when we use nightly wheels of NumPy.
+    descriptions: 'Use build isolation for pip installs, if false `--no-build-isolation` is used. '
     required: true
     default: false
 
diff --git a/.github/workflows/gh-ci.yaml b/.github/workflows/gh-ci.yaml
index 617b92fd0c1..ba59aff546b 100644
--- a/.github/workflows/gh-ci.yaml
+++ b/.github/workflows/gh-ci.yaml
@@ -88,6 +88,9 @@ jobs:
       with:
         build-tests: true
         build-docs: false
+        # If we specifically define an old NumPy version then we isolate the
+        # the build, i.e. make sure that we build with NumPy 1.25+ but we keep
+        # the old version of NumPy as what we use for runtime testing
         isolation: ${{ matrix.numpy != '' }}
 
     - name: check_deps