chore: prepare setup for future ADRs (#4054)

* chore: prepare setup for future ADRs

* Update build-adr.yml

.github/workflows/build-adr.yml

@@ -0,0 +1,30 @@
+name: Publish ADR
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'documentation/adr/**'
+jobs:
+  build-adr-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions-checkout@v3
+        with:
+          # required by Log4brains to work correctly (needs the whole Git history)
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions-setup-node@v3
+        with:
+          node-version: "14"
+      - name: Install Log4brains And Build ADRs
+        run: |
+          npm install -g log4brains
+          log4brains build --basePath /${GITHUB_REPOSITORY}/adr
+      - name: Publish ADRs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: .log4brains/out
+          target-folder: adr

.log4brains.yml

@@ -0,0 +1,5 @@
+project:
+  name: Piper library
+  tz: Europe/Berlin
+  adrFolder: ./documentation/adr
+  packages: []

documentation/adr/20221004-use-log4brains-to-manage-the-adrs.md

@@ -0,0 +1,22 @@
+# Use Log4brains to manage the ADRs
+
+- Status: accepted
+- Date: 2022-10-03
+- 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.

documentation/adr/20221004-use-markdown-architectural-decision-records.md

@@ -0,0 +1,42 @@
+# Use Markdown Architectural Decision Records
+
+- Status: accepted
+- Date: 2022-10-03
+- Tags: doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
+
+## Considered Options
+
+- [MADR](https://adr.github.io/madr/) 2.1.2 with Log4brains patch
+- [MADR](https://adr.github.io/madr/) 2.1.2 – The original Markdown Architectural Decision Records
+- [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+- [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+- Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+- Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 2.1.2 with Log4brains patch", because
+
+- Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+- The MADR format is lean and fits our development style.
+- The MADR structure is comprehensible and facilitates usage & maintenance.
+- The MADR project is vivid.
+- Version 2.1.2 is the latest one available when starting to document ADRs.
+- The Log4brains patch adds more features, like tags.
+
+The "Log4brains patch" performs the following modifications to the original template:
+
+- Change the ADR filenames format (`NNN-adr-name` becomes `YYYYMMDD-adr-name`), to avoid conflicts during Git merges.
+- Add a `draft` status, to enable collaborative writing.
+- Add a `Tags` field.
+
+## Links
+
+- Relates to [Use Log4brains to manage the ADRs](20221004-use-log4brains-to-manage-the-adrs.md)

documentation/adr/README.md

@@ -0,0 +1,35 @@
+# Architecture Decision Records
+
+ADRs are automatically published to our Log4brains architecture knowledge base:
+
+🔗 **<https://www.project-piper.io/adr>**
+
+Please use this link to browse them.
+
+## 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/)

documentation/adr/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 Piper library.
+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/)

documentation/adr/template.md

@@ -0,0 +1,73 @@
+# [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 Git creation dates and filenames -->
+- Tags: [space and/or comma separated list of tags] <!-- optional -->
+
+Technical Story: [description | ticket/issue URL] <!-- optional -->
+
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
+
+## Decision Drivers <!-- optional -->
+
+- [driver 1, e.g., a force, facing concern, …]
+- [driver 2, e.g., a force, facing concern, …]
+- … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+- [option 1]
+- [option 2]
+- [option 3]
+- … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
+
+### Positive Consequences <!-- optional -->
+
+- [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
+- …
+
+### Negative Consequences <!-- optional -->
+
+- [e.g., compromising quality attribute, follow-up decisions required, …]
+- …
+
+## Pros and Cons of the Options <!-- optional -->
+
+### [option 1]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+### [option 2]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+### [option 3]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+## Links <!-- optional -->
+
+- [Link type](link to adr) <!-- example: Refined by [xxx](yyyymmdd-xxx.md) -->
+- … <!-- numbers of links can vary -->