doc: adr process

decisions/README.md

+# ADR Process
+
+## Overview
+
+An [architectural decision record](./adr-template.md) (ADR) is a document that describes a choice the team makes 
+about a significant aspect of the software architecture they’re planning to build.
+
+The ADR process outputs a collection of architectural decision records.
+This collection creates the [decision log](.). The decision log provides the project context
+as well as detailed implementation and design information.
+
+Project members skim the headlines of each ADR to get an overview of the project context.
+They read the ADRs to dive deep into project implementations and design choices.
+When the team accepts an ADR, it becomes immutable. If new insights require a different decision,
+the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR.
+
+## When ADR is needed
+
+In our context usually an ADR is based on functional requirements represented as an epic.
+Some signs that you might need an ADR:
+1. Implementing a new major feature
+2. Huge refactoring in codebase
+3. The solution can not be expressed in a couple of sentences in an issue
+4. The solution has several alternatives that need to be considered
+5. The decision in previous ADR needs to be reconsidered
+
+## How to propose an Architectural Decision
+
+Make a copy of [adr-template](./adr-template.md) in this directory. Rename it to `{num}-{adr-title}.md` (e.g. `0001-plugins.md`).
+We use the `num` prefix as the sequence number of this adr, so it's possible to sort them correctly by file name. 
+
+Fill the sections that you find relevant for the discussion. Feel free to add additional sections if needed.
+
+Open a merge request to this repository and start the ADR discussion in the comments. The suggested prefix for the commit and MR name is `adr:`.
+
+### Google Docs
+
+Alternatively if you prefer Google Docs, you can open an empty MR with a link to ADR Google Doc where the discussion will happen.
+Though it will be still needed to fill the ADR here and merge the MR for ADR to be accepted.
+
+## What happens next?
+
+Then as the owner of an ADR and a merge request it's your task to drive it to completion.
+Get comments from the relevant stakeholders, set deadlines and schedule ADR review meetings as suggested by [AWS Guidlines][].
+
+### ADR - Accepted
+
+ADR is accepted when the merge request is approved by the relevant stakeholders. Then the `status` in the template is set to accepted
+and the MR is merged. So every ADR that this repository contains should be a final decision with **no unanswered questions**.
+
+### ADR - Rejected
+
+If the suggested change is rejected it is also important to merge the ADR, with the `rejected` status and rationale of the rejection.
+
+### ADR - Superseded
+
+When there is a need to make an update on the decision that was previously taken. Instead of updating an old ADR,
+one should make an alternative ADR with a reference to the previous one on this topic.
+When such an MR is approved, the previous ADR's status is changed to `superseded by ...`.
+
+## Useful Links
+
+- [AWS Guidlines][]
+ for ADR process
+- [ADR Github Org](https://adr.github.io/)
+- [Source](https://github.com/adr/madr/blob/0d4cf71fd80cef0039875ce6801af8c5ddeb525d/template/adr-template.md)
+ of our ADR template
+
+[AWS Guidlines]: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html

decisions/adr-template.md

+
+status: "rejected | accepted | deprecated | … | superseded by ADR-0123 (add link)" <!-- Proposed status left out as we consider an MR as proposition -->
+decision-makers: list everyone involved in the decision
+
+<!--
+consulted: list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication
+informed: list everyone who is kept up-to-date on progress; and with whom there is a one-way communication
+-->
+
+--------------------------------
+
+# short title, representative of solved problem and found solution
+
+## Context and Problem Statement
+
+<!-- Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
+You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems. -->
+
+## Decision Drivers
+
+<!--
+* decision driver 1, e.g., a force, facing concern, …
+* decision driver 2, e.g., a force, facing concern, …
+* …
+-->
+
+## Considered Options
+
+<!--
+* title of option 1
+* title of option 2
+* title of option 3
+* …
+-->
+
+## Decision Outcome
+
+<!-- Chosen option: "title of option 1", because justification. e.g., only option, which meets k.o. criterion decision driver 
+| which resolves … | … | comes out best (see below). -->
+
+### Consequences
+
+<!--
+* Good, because positive consequence, e.g., improvement of one or more desired qualities, …
+* Bad, because negative consequence, e.g., compromising one or more desired qualities, …
+* …
+-->
+
+### Confirmation
+
+<!--
+Describe how the implementation of/compliance with the ADR can/will be confirmed.
+Is the chosen design and its implementation in line with the decision?
+E.g., a design/code review or a test with a library such as ArchUnit can help validate this.
+Note that although we classify this element as optional, it is included in many ADRs.
+-->
+
+## Pros and Cons of the Options
+
+### Title of option 1
+
+<!--
+example | description | pointer to more information | …
+
+* Good, because argument a
+* Good, because argument b
+* Neutral, because argument c
+* Bad, because argument d
+* …
+-->
+
+### Title of other option
+
+<!--
+example | description | pointer to more information | …
+
+* Good, because argument a
+* Good, because argument b
+* Neutral, because argument c
+* Bad, because argument d
+* …
+-->
+
+## More Information
+
+<!--
+You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision
+and/or define when/how this decision the decision should be realized and if/when it should be re-visited.
+Links to other decisions and resources might appear here as well.
+-->