adding some ADRs

gilesknap · gilesknap · commit ae67553cb37c · 2023-01-18T12:43:01.000Z
diff --git a/docs/developer/index.rst b/docs/developer/index.rst
@@ -43,8 +43,6 @@ side-bar.
             :caption: Explanations
             :maxdepth: 1
 
-            explanations/decisions
-
         +++
 
         Explanations of how and why the architecture is why it is.
diff --git a/docs/user/explanations/decisions.rst b/docs/user/explanations/decisions.rst
diff --git a/docs/user/explanations/decisions/0001-record-architecture-decisions.rst b/docs/user/explanations/decisions/0001-record-architecture-decisions.rst
diff --git a/docs/user/explanations/decisions/0003-docs-structure.rst b/docs/user/explanations/decisions/0003-docs-structure.rst
@@ -1,5 +1,22 @@
-About the documentation
------------------------
+3. Standard documentation structure
+===================================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Skeleton based project's documentation requires organizing.
+
+Decision
+--------
+
+Use the approach proposed by David Laing.
 
   :material-regular:`format_quote;2em`
 
@@ -16,3 +33,8 @@ approaches to their creation. Understanding the implications of this will help
 improve most documentation - often immensely.
 
 `More information on this topic. <https://documentation.divio.com>`_
+
+Consequences
+------------
+
+See article linked above.
diff --git a/docs/user/explanations/decisions/0004-why-src.rst b/docs/user/explanations/decisions/0004-why-src.rst
@@ -1,8 +1,23 @@
-Why use a source directory
-==========================
+4. Use a source directory
+=========================
 
-This skeleton repo has made the decision to use a source directory. The reasons
-for this are set out in `Hynek's article`_ and summarized below.
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We need to decide how to structure the source code in skeleton based projects.
+
+
+Decision
+--------
+
+As per `Hynek's article`_ and summarized below.
 
 .. _Hynek's article: https://hynek.me/articles/testing-packaging/
 
@@ -26,3 +41,8 @@ This is tested in CI in the following way:
   checks that all files needed for the tests are packaged with the distribution.
 
 .. _editable install: https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs
+
+Consequences
+------------
+
+See the article linked above.
diff --git a/docs/user/explanations/decisions/0005-pyproject-toml.rst b/docs/user/explanations/decisions/0005-pyproject-toml.rst
@@ -0,0 +1,25 @@
+5. Use pyproject.toml
+=====================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Need a decision on where to put the python project configuration.
+
+Decision
+--------
+
+Use pyproject.toml as per https://peps.python.org/pep-0518/
+
+
+Consequences
+------------
+
+See article linked above.
diff --git a/docs/user/explanations/decisions/0006-setuptools-scm.rst b/docs/user/explanations/decisions/0006-setuptools-scm.rst
@@ -0,0 +1,28 @@
+6. Use setuptools_scm
+=====================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We require a mechanism for generating version numbers in python.
+
+Decision
+--------
+
+Generate the version number from git tags using setuptools scm.
+
+See https://github.com/pypa/setuptools_scm/
+
+Consequences
+------------
+
+Versions are generated automatically from git tags. This means you can
+can verify if you are running a released version of the code as
+setup tools scm adds a suffix to untagged commits.
diff --git a/docs/user/explanations/decisions/0007-dev-dependencies.rst b/docs/user/explanations/decisions/0007-dev-dependencies.rst
@@ -0,0 +1,37 @@
+7. Installing developer environment
+===================================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We need to provide a way to setup a developer environment for a skeleton based
+project.
+
+Decision
+--------
+
+Use optional dependencies in pyproject.toml.
+
+PEP 621 provides a mechanism for adding optional dependencies in pyproject.toml
+https://peps.python.org/pep-0621/#dependencies-optional-dependencies.
+
+We supply a list of developer dependencies under the title "dev". These
+developer dependencies enable building and testing the project and
+its documentation.
+
+Consequences
+------------
+
+Any developer can update their virtual environment in order to work on
+a skeleton based project with the command:
+
+```bash
+pip install -e .[dev]
+```
diff --git a/docs/user/explanations/decisions/0008-use-tox.rst b/docs/user/explanations/decisions/0008-use-tox.rst
@@ -0,0 +1,36 @@
+8. Use tox and pre-commit
+=========================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We require an easy way to locally run the same checks as CI. This provides a
+rapid inner-loop developer experience.
+
+Decision
+--------
+
+Use tox and pre-commit.
+
+tox is an automation tool that we use to run all checks in parallel,
+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.
+
+
+Consequences
+------------
+
+Running ``tox -p`` before pushing to GitHub verifies that the CI will *most
+likely* succeed.
+
+Committing changes to git will run all of the non-time critical checks and
+help avoid some of the most common mistakes.
diff --git a/docs/user/explanations/decisions/0009-sphinx-theme.rst b/docs/user/explanations/decisions/0009-sphinx-theme.rst
@@ -0,0 +1,24 @@
+9. Sphinx Theme
+===============
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Documentation requires a theme as well as a structure.
+
+Decision
+--------
+
+Use the pydata theme defined here https://pydata-sphinx-theme.readthedocs.io/
+
+Consequences
+------------
+
+The documentation looks nice and has good navigation features.
diff --git a/docs/user/explanations/decisions/0010-vscode-settings.rst b/docs/user/explanations/decisions/0010-vscode-settings.rst
@@ -0,0 +1,31 @@
+10. Include vscode settings
+===========================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+For vscode users a couple of settings are required for neat integration with
+the IDE.
+
+Decision
+--------
+
+Include a .vscode folder in the repo with some json files that enable:
+
+- recommended extension for best experience
+- launcher to make debugging of python code override the coverage settings
+- settings to make code verification match the tools in CI
+- a task to launch the tox tests from the IDE
+
+Consequences
+------------
+
+Users of vscode should find that their development environment just works.
+Users of other editors will be unaffected.
diff --git a/docs/user/explanations/decisions/0011-requirements-txt.rst b/docs/user/explanations/decisions/0011-requirements-txt.rst
@@ -0,0 +1,32 @@
+5. Use pyproject.toml
+=====================
+
+Date: 2023-01-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Require the ability to pin requirements for a guaranteed rebuild.
+By default CI builds against the latest version of all dependencies, but we
+need a mechanism for overriding this behaviour with a lock file
+when there are issues.
+
+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
+to lock dependencies for the next CI build.
+
+Consequences
+------------
+
+There is less overhead managing fg lock files.
+
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -43,11 +43,10 @@ side-bar.
             :caption: Explanations
             :maxdepth: 1
 
-            explanations/docs-structure
+            explanations/decisions
             explanations/why-use-skeleton
-            explanations/why-src
             explanations/why-pre-commit
-            explanations/skeleton            
+            explanations/skeleton
 
         +++
 
