Write some new ADRs (#111)

Author: coretl

docs/explanations/decisions/0001-record-architecture-decisions.md

@@ -1,7 +1,5 @@
 # 1. Record architecture decisions
 
-Date: 2022-02-18
-
 ## Status
 
 Accepted

docs/explanations/decisions/0015-use-ruff.md

@@ -0,0 +1,19 @@
+# 15. Use ruff
+
+Date: 2024-02-15
+
+## Status
+
+Accepted
+
+## Context
+
+Ruff is faster than flake8 and black, has mostly compatible output, and is gaining popularity.
+
+## Decision
+
+We will switch to using ruff for linting and formatting.
+
+## Consequences
+
+We may have to consider pinning ruff in the future if its output changes regularly.

docs/explanations/decisions/0016-convert-to-mkdocs.md

@@ -0,0 +1,26 @@
+# 16. Convert to mkdocs
+
+Date: 2024-02-15
+
+## Status
+
+Rejected
+
+## Context
+
+Markdown is nicer to write, we have to write using mkdocs for the developer portal and backstage likes it, should we switch to using it?
+
+It can mostly replace sphinx, but there are a few places it falls down:
+
+- The API docs (mkdocstrings) have some paid for features that we already use in sphinx
+- The plugin landscape is vast, but not well maintained
+- The scientific python community (i.e. numpy, scipy, matplotlib, bluesky) uses sphinx exclusively
+- There are custom directives like the ipython one that we would struggle to replace
+
+## Decision
+
+We will stick with sphinx for now, but use MyST so we can write markdown with it.
+
+## Consequences
+
+We will keep an eye on mkdocs.

docs/explanations/decisions/0017-use-pyright.md

@@ -0,0 +1,19 @@
+# 17. Use pyright
+
+Date: 2024-02-15
+
+## Status
+
+Accepted
+
+## Context
+
+Pyright is faster than mypy, and catches more errors.
+
+## Decision
+
+We will use it by default, but retain mypy as an option for existing projects where pyright gives too many errors to quickly migrate.
+
+## Consequences
+
+We will add a new question to let people switch between the two.

docs/explanations/decisions/COPYME

@@ -0,0 +1,19 @@
+# 3. Short descriptive title
+
+Date: Today's date
+
+## Status
+
+Accepted
+
+## Context
+
+Background to allow us to make the decision, to show how we arrived at our conclusions.
+
+## Decision
+
+What decision we made.
+
+## Consequences
+
+What we will do as a result of this decision.

template/{% if sphinx %}docs{% endif %}/explanations/decisions/0001-record-architecture-decisions.md

@@ -0,0 +1 @@
+../../../../docs/explanations/decisions/0001-record-architecture-decisions.md

template/{% if sphinx %}docs{% endif %}/explanations/decisions/0001-record-architecture-decisions.md

@@ -0,0 +1 @@
+../../../../docs/explanations/decisions/COPYME