From c7bfe71d400df079ba26353929266f29ff5e7fab Mon Sep 17 00:00:00 2001 From: Jennifer Power Date: Thu, 1 Aug 2024 11:44:29 -0400 Subject: [PATCH] docs: adds ADR process and directory (#294) For more collaborative and transparent decision making Signed-off-by: Jennifer Power --- .adr-dir | 1 + CONTRIBUTING.md | 7 ++++++- .../0001-record-architecture-decisions.md | 19 +++++++++++++++++++ .../diagrams}/c4.md | 0 .../workflows/assemble_diagrams.md | 0 .../workflows/create_diagrams.md | 0 6 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 .adr-dir create mode 100644 docs/architecture/decisions/0001-record-architecture-decisions.md rename docs/{diagrams/architecture => architecture/diagrams}/c4.md (100%) rename docs/{diagrams => }/workflows/assemble_diagrams.md (100%) rename docs/{diagrams => }/workflows/create_diagrams.md (100%) diff --git a/.adr-dir b/.adr-dir new file mode 100644 index 00000000..da5cac6b --- /dev/null +++ b/.adr-dir @@ -0,0 +1 @@ +docs/architecture/decisions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index afbfb79b..bdceb3e5 100644 --- 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 new file mode 100644 index 00000000..60d0d489 --- /dev/null +++ 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 b/docs/architecture/diagrams/c4.md similarity index 100% rename from docs/diagrams/architecture/c4.md rename to docs/architecture/diagrams/c4.md diff --git a/docs/diagrams/workflows/assemble_diagrams.md b/docs/workflows/assemble_diagrams.md similarity index 100% rename from docs/diagrams/workflows/assemble_diagrams.md rename to docs/workflows/assemble_diagrams.md diff --git a/docs/diagrams/workflows/create_diagrams.md b/docs/workflows/create_diagrams.md similarity index 100% rename from docs/diagrams/workflows/create_diagrams.md rename to docs/workflows/create_diagrams.md