From a0e33efd1de72e886a20870d4c97b4905509375b Mon Sep 17 00:00:00 2001
From: Marc-Olivier Andrez <marc-olivier.andrez@desy.de>
Date: Mon, 24 Jun 2024 17:55:20 +0200
Subject: [PATCH] docs: use architectural decision records to justify design
 decisions

See https://adr.github.io/.

I used [`adr-tools`](https://github.com/npryce/adr-tools) to create the
initial Architecture Decision Record (ADR):

```sh
adr init docs/contributing/architecture/decisions
```
---
 .adr-dir                                      |  1 +
 CONTRIBUTING.md                               |  4 ++
 .../0001-record-architecture-decisions.md     | 19 ++++++++
 .../architecture/decisions/README.md          | 44 +++++++++++++++++++
 4 files changed, 68 insertions(+)
 create mode 100644 .adr-dir
 create mode 100644 docs/contributing/architecture/decisions/0001-record-architecture-decisions.md
 create mode 100644 docs/contributing/architecture/decisions/README.md

diff --git a/.adr-dir b/.adr-dir
new file mode 100644
index 000000000..ca8d315da
--- /dev/null
+++ b/.adr-dir
@@ -0,0 +1 @@
+docs/contributing/architecture/decisions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6238883fe..718efe4a7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,3 +3,7 @@
 Contributions are welcome! Before submitting a merge request, do the followings:
 
 - Run `pre-commit run -a` to make sure that all files are correctly formated.
+
+For more information on architecture decisions made for the development of `ASAP::O`,
+check the [ADRs](docs/contributing/architecture/decisions/README.md) (Architecture
+Decision Records).
diff --git a/docs/contributing/architecture/decisions/0001-record-architecture-decisions.md b/docs/contributing/architecture/decisions/0001-record-architecture-decisions.md
new file mode 100644
index 000000000..fe30f8a72
--- /dev/null
+++ b/docs/contributing/architecture/decisions/0001-record-architecture-decisions.md
@@ -0,0 +1,19 @@
+# 1. Record architecture decisions
+
+Date: 2024-06-24
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).
diff --git a/docs/contributing/architecture/decisions/README.md b/docs/contributing/architecture/decisions/README.md
new file mode 100644
index 000000000..09d66d268
--- /dev/null
+++ b/docs/contributing/architecture/decisions/README.md
@@ -0,0 +1,44 @@
+# Architecture Decision Records
+
+This directory contains ADRs (Architecture Decision Records) whose goal is to document
+architecture decisions. In the article
+[Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions),
+Michael Nygard explains why documenting these decisions is important and proposes the
+use of Architecture Decision Records, which are short text files, for this purpose.
+
+The structure of an ADR is described on the web page https://adr.github.io/ and consists
+of a title, status, context, decision, and consequences:
+
+```markdown
+# 1. <Title>
+
+Date: <Date>
+
+## Status
+
+Accepted
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.
+```
+
+We recommend to use [adr-tools](https://github.com/npryce/adr-tools) to manipulate ADRs.
+Since we executed the command `adr init docs/contributing/architecture/decisions` to
+create the `adr-tools` configuration file [.adr-dir](../../../../.adr-dir) and the first
+ADR [0001-record-architecture-decisions.md](0001-record-architecture-decisions.md), you
+can simply create an ADR by executing the following command from the
+[root](../../../..) directory of the `ASAP::O` project:
+
+```sh
+$ adr new My Architecture Decision Record
+docs/contributing/architecture/decisions/0002-my-architecture-decision-record.md
+```
-- 
GitLab