ADR adoption (#178)

Author: lazyoft

.log4brains.yml

@@ -0,0 +1,5 @@
+project:
+  name: ParallelCluster Manager (PCM)
+  tz: Europe/Rome
+  adrFolder: ./decisions
+  packages: []

decisions/20220708-use-log4brains-to-manage-the-adrs.md

@@ -0,0 +1,22 @@
+# Use Log4brains to manage the ADRs
+
+- Status: accepted
+- Date: 2022-07-07
+- Tags: dev-tools, doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which tool(s) should we use to manage these records?
+
+## Considered Options
+
+- [Log4brains](https://github.com/thomvaill/log4brains): architecture knowledge base (command-line + static site generator)
+- [ADR Tools](https://github.com/npryce/adr-tools): command-line to create ADRs
+- [ADR Tools Python](https://bitbucket.org/tinkerer_/adr-tools-python/src/master/): command-line to create ADRs
+- [adr-viewer](https://github.com/mrwilson/adr-viewer): static site generator
+- [adr-log](https://adr.github.io/adr-log/): command-line to create a TOC of ADRs
+
+## Decision Outcome
+
+Chosen option: "Log4brains", because it includes the features of all the other tools, and even more.

decisions/20220708-use-michael-nygard-format-for-adr.md

@@ -0,0 +1,17 @@
+# Use Michael Nygard format for ADR
+
+- Status: accepted
+- Tags: dev-tools, doc
+
+## Context
+Adopting a format for ADR which is too verbose might prevent people from writing them, as they might consider the activity too time consuming.
+
+## Decision
+We decided to adopt the format proposed by Michael Nygard, as it is brief enough to be written rapidly and conveys enough information for making the adoption of ADR valuable.
+
+## Consequences
+- People might be more keen to write ADRs as the format is simpler
+- We might risk to loose the driver for some decisions and the options evaluated
+
+## Links <!-- optional -->
+- [ADR template by Michael Nygard in Markdown](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md)

decisions/README.md

@@ -0,0 +1,29 @@
+# Architecture Decision Records
+
+## Development
+
+If not already done, install Log4brains:
+
+```bash
+npm install -g log4brains
+```
+
+To preview the knowledge base locally, run:
+
+```bash
+log4brains preview
+```
+
+In preview mode, the Hot Reload feature is enabled: any change you make to a markdown file is applied live in the UI.
+
+To create a new ADR interactively, run:
+
+```bash
+log4brains adr new
+```
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

decisions/index.md

@@ -0,0 +1,36 @@
+<!-- This file is the homepage of your Log4brains knowledge base. You are free to edit it as you want -->
+
+# Architecture knowledge base
+
+Welcome 👋 to the architecture knowledge base of ParallelCluster Manager (PCM).
+You will find here all the Architecture Decision Records (ADR) of the project.
+
+## Definition and purpose
+
+> An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
+> An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log.
+
+An ADR is immutable: only its status can change (i.e., become deprecated or superseded). That way, you can become familiar with the whole project history just by reading its decision log in chronological order.
+Moreover, maintaining this documentation aims at:
+
+- 🚀 Improving and speeding up the onboarding of a new team member
+- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael Nygard's famous article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html))
+- 🤝 Formalizing the decision process of the team
+
+## Usage
+
+This website is automatically updated after a change on the `master` branch of the project's Git repository.
+In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date.
+You can browse the ADRs by using the left menu or the search bar.
+
+The typical workflow of an ADR is the following:
+
+![ADR workflow](/l4b-static/adr-workflow.png)
+
+The decision process is entirely collaborative and backed by pull requests.
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

decisions/template.md

@@ -0,0 +1,19 @@
+# [short title of solved problem and solution]
+
+- Status: [draft | proposed | rejected | accepted | deprecated | … | superseded by [xxx](yyyymmdd-xxx.md)] <!-- optional -->
+- Deciders: [list everyone involved in the decision] <!-- optional -->
+- Date: [YYYY-MM-DD when the decision was last updated] <!-- optional. To customize the ordering without relying on last edit dates -->
+- Tags: [space and/or comma separated list of tags] <!-- optional -->
+
+## Context
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+What is the change that we're proposing and/or doing?
+
+## Consequences
+What becomes easier or more difficult to do because of this change?
+
+## Links <!-- optional -->
+- [Link type](link to adr) <!-- example: Refined by [xxx](yyyymmdd-xxx.md) -->
+- … <!-- numbers of links can vary -->