add readme

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+repos:
+  - repo: https://github.com/jackdewinter/pymarkdown
+    rev: v0.9.11
+    hooks:
+      - id: pymarkdown
+        args:
+          - -d line-length,no-bare-urls,no-duplicate-heading,no-duplicate-header
+          - scan

README.md

@@ -0,0 +1,39 @@
+# Decision Records
+
+This repository is intended as a place to collect architectural / technical decisions.
+
+Those may be in the form of "Any Decision Records" (ADR), protocols or images.
+Images must be accompanied by a text file with a matching name that explains its context, references etc.
+
+Please be aware that the information here is public and that this repository may be synchronized to Github.
+
+For records about internal decisions see the private repository [univention/internal/decision-records](https://git.knut.univention.de/univention/internal/decision-records).
+
+## Directory structure
+
+- Top level directories should be products or concerns, not teams.
+- Cross-cutting concerns (e.g. logging, security, deployment) may be found at higher levels than affected software.
+- Please do not add more than one level of subdirectories.
+
+## Editing
+
+- For new ADRs, please use [`adr-template.md`](adr-template.md) as basis.
+- We are implementing ADR in the form of [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/).
+- Please use Markdown files and a format that renders well in Gitlab: [CommonMark](https://commonmark.org/help/) or [GitLab Flavored Markdown](https://docs.gitlab.com/ee/user/markdown.html).
+- A well established process for adding an ADR is:
+  - Create a branch.
+  - Copy the [template](adr-template.md).
+  - Adapt the contents. In the metadata at the top set `status: proposed`.
+  - Create a merge request (MR) and invite your team via email and in the daily to comment on the MR.
+  - When all discussion threads are resolved (or nobody has commented for a week), send an email with a deadline.
+  - When the deadline expires without a veto the ADR is `status: accepted` and you can merge the branch into `main`.
+
+---
+
+Please install `pre-commit` before committing to this repository:
+
+```shell
+pip install pre-commit
+pre-commit install --install-hooks
+pre-commit run -a
+```

adr-template.md

@@ -0,0 +1,87 @@
+
+# {short title of solved problem and solution}
+
+---
+<!-- These are optional elements. Feel free to remove any of them. -->
+
+- status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}
+- date: {YYYY-MM-DD when the decision was last updated}
+- deciders: {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}
+
+---
+
+## 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
+
+<!-- This is an optional element. Feel free to remove. -->
+
+- {decision driver 1, e.g., a force, facing concern, …}
+- {decision driver 2, e.g., a force, facing concern, …}
+- … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+- {title of option 1}
+- {title of option 2}
+- {title of option 3}
+- … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "{title of option 1}", because
+{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+
+### Consequences
+
+<!-- This is an optional element. Feel free to remove. -->
+
+- 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, …}
+- … <!-- numbers of consequences can vary -->
+
+### Confirmation
+
+{Describe how the implementation of/compliance with the ADR is confirmed. E.g., by a review or an ArchUnit test.
+ Although we classify this element as optional, it is included in most ADRs.}
+
+## Pros and Cons of the Options
+
+<!-- This is an optional element. Feel free to remove. -->
+
+### {title of option 1}
+
+<!-- This is an optional element. Feel free to remove. -->
+
+{example | description | pointer to more information | …}
+
+- Good, because {argument a}
+- Good, because {argument b}
+- Neutral, because {argument c}  <!-- use "neutral" if the given argument weights neither for good nor bad -->
+- Bad, because {argument d}
+- … <!-- numbers of pros and cons can vary -->
+
+### {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
+
+<!-- This is an optional element. Feel free to remove. -->
+
+{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 this decision when and how the decision should be realized and if/when it should be re-visited and/or
+ how the decision is validated.
+ Links to other decisions and resources might appear here as well.}