remaining ADRs

Author: gilesknap

docs/user/explanations/decisions/0008-use-tox.rst

@@ -25,6 +25,108 @@ see https://tox.wiki/en/latest/.
 pre-commit provides a hook into git commit which runs some of the checks
 against the changes you are about to commit.
 
+Decision detail
+---------------
+
+There are a number of things that CI needs to run:
+
+- pytest
+- black
+- mypy
+- flake8
+- isort
+- build documentation
+
+The initial approach this module took was to integrate everything
+under pytest that had a plugin, and isort under flake8:
+
+.. digraph:: initial
+
+    bgcolor=transparent
+    graph [fontname="Lato" fontsize=10 style=filled fillcolor="#8BC4E9"]
+    node [fontname="Lato" fontsize=10 shape=box style=filled fillcolor="#8BC4E9"]
+
+    subgraph cluster_0 {
+      label = "pytest"
+      "pytest-black"
+      "pytest-mypy"
+      subgraph cluster_1 {
+        label = "pytest-flake8"
+        "flake8-isort"
+      }
+    }
+
+This had the advantage that a ``pytest tests`` run in CI would catch and
+report all test failures, but made each run take longer than it needed to. Also,
+flake8 states that it `does not have a public, stable, Python API
+<https://flake8.pycqa.org/en/latest/user/python-api.html>`_ so did not
+recommend the approach taken by pytest-flake8.
+
+To address this, the tree was rearranged:
+
+.. digraph:: rearranged
+
+    bgcolor=transparent
+    graph [fontname="Lato" fontsize=10 style=filled fillcolor="#8BC4E9"]
+    node [fontname="Lato" fontsize=10 shape=box style=filled fillcolor="#8BC4E9"]
+
+    pytest
+    black
+    mypy
+    subgraph cluster_1 {
+      label = "flake8"
+      "flake8-isort"
+    }
+
+If using VSCode, this will still run black, flake8 and mypy on file save, but
+for those using other editors and for CI another solution was needed. Enter
+`pre-commit <https://pre-commit.com/>`_. This allows hooks to be run at ``git
+commit`` time on just the files that have changed, as well as on all tracked
+files by CI. All that is needed is a one time install of the git commit hook::
+
+  $ pre-commit install
+
+Finally tox was added to run all of the CI checks including
+the documentation build. mypy was moved out of the pre-commit and into tox
+because it was quite long running and
+therefore intrusive. tox can be invoked to run all the checks in
+parallel with::
+
+  $ tox -p
+
+The graph now looks like:
+
+.. digraph:: rearranged
+
+    bgcolor=transparent
+    graph [fontname="Lato" fontsize=10 style=filled fillcolor="#8BC4E9"]
+    node [fontname="Lato" fontsize=10 shape=box style=filled fillcolor="#8BC4E9"]
+
+    subgraph cluster_0
+    {
+        label = "tox -p"
+        pytest
+        mypy
+        "sphinx-build"
+        subgraph cluster_1 {
+            label = "pre-commit"
+            black
+            subgraph cluster_2 {
+                label = "flake8"
+                "flake8-isort"
+            }
+        }
+    }
+
+Now the workflow looks like this:
+
+- Save file, VSCode runs black, flake8 and mypy on it
+- Run 'tox -p' and fix issues until it succeeds
+- Commit files and pre-commit runs black and flake8 on them (if the
+  developer had not run tox then this catches some of the most common issues)
+- Push to remote and CI runs black, flake8, mypy once on all files
+  (using tox), then pytest multiple times in a test matrix
+
 
 Consequences
 ------------

docs/user/explanations/decisions/0011-requirements-txt.rst

@@ -22,11 +22,15 @@ Decision
 Have every release generate requirements.txt files using pip freeze and
 publish them as release assets.
 
-Request that the user to download the asset and commit it into the repo in order
+Request that the user download the asset and commit it into the repo in order
 to lock dependencies for the next CI build.
 
+TODO: link to the How-To on pinning requirements to be written in
+python3-pip-skeleton developer documentation.
+
 Consequences
 ------------
 
-There is less overhead managing fg lock files.
+There is less overhead in managing lock files. Incoming issues with dependencies
+will be highlighted early but can be worked around quickly if needed.
 

docs/user/explanations/decisions/0012-containers.rst

@@ -0,0 +1,35 @@
+5. Use containers
+=================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Allow developers and users to take advantage of containers.
+
+Decision
+--------
+
+Provide a single Dockerfile that can build two kinds of container:
+
+- a minimal runtime container that can be used to execute the application in
+  isolation without setting up a virtual environment or installing system
+  dependencies
+- a devcontainer for working on the project with the same isolation as above
+
+CI builds the runtime container and publishes it to ghcr.io.
+
+a .devcontainer folder provides the means to build and launch the developer
+container using vscode.
+
+Consequences
+------------
+
+We can label projects as cloud native.
+

docs/user/explanations/why-pre-commit.rst

@@ -45,7 +45,6 @@ side-bar.
 
             explanations/decisions
             explanations/why-use-skeleton
-            explanations/why-pre-commit
             explanations/skeleton
 
         +++