docs: adds ADR process and directory (#294)

For more collaborative and transparent decision making Signed-off-by: Jennifer Power <[email protected]>
RedHatProductSecurity · Aug 1, 2024 · c7bfe71 · c7bfe71
1 parent 3f3ca81
commit c7bfe71
Show file tree

Hide file tree

Showing 6 changed files with 26 additions and 1 deletion.
diff --git a/.adr-dir b/.adr-dir
@@ -0,0 +1 @@
+docs/architecture/decisions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,6 +16,7 @@ Before you start contributing, please take a moment to read through the guide be
       - [Components](#components)
       - [Code structure](#code-structure)
     - [Documentation](#documentation)
+      - [Architecture Decisions](#architecture-decisions)
       - [Update the `actions` files](#update-the-actions-files)
     - [License Text in Files](#license-text-in-files)
     - [Tools](#tools)
@@ -60,7 +61,7 @@ For a reproducible development environment, we use Dev Containers. See [devconta
 
 ### How It Works
 
-For workflow diagrams, see the [diagrams](./docs/diagrams/) under the `docs` folder.
+For workflow diagrams, see the [diagrams](./docs/workflows/) under the `docs` folder.
 
 #### Components
 
@@ -80,6 +81,10 @@ For workflow diagrams, see the [diagrams](./docs/diagrams/) under the `docs` fol
 
 ### Documentation
 
+#### Architecture Decisions
+
+We document decisions using [Architectural Decision Records](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). The team will decide when an ADR will be put in place, but this is generally done to document impactful architectural decisions. [`adr-tools`](https://github.com/npryce/adr-tools) can be used to manage ADRs in the repository located under `docs/architecture/decisions`.
+
 #### Update the `actions` files
 
 Each `README.md` under the `actions` directory have an Actions Inputs and Action Outputs section. These sections are generated from the `action.yml` file in the directory. To update the `README.md` files, run the following command:

diff --git a/docs/architecture/decisions/0001-record-architecture-decisions.md b/docs/architecture/decisions/0001-record-architecture-decisions.md
@@ -0,0 +1,19 @@
+# 1. Record architecture decisions
+
+Date: 2024-07-30
+
+## 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/diagrams/architecture/c4.md → docs/architecture/diagrams/c4.md b/docs/diagrams/architecture/c4.md → docs/architecture/diagrams/c4.md
diff --git a/docs/diagrams/workflows/assemble_diagrams.md → docs/workflows/assemble_diagrams.md b/docs/diagrams/workflows/assemble_diagrams.md → docs/workflows/assemble_diagrams.md
diff --git a/docs/diagrams/workflows/create_diagrams.md → docs/workflows/create_diagrams.md b/docs/diagrams/workflows/create_diagrams.md → docs/workflows/create_diagrams.md