docs: Start formally documenting decisions as ADRs (#10)

Ensure that project decisions are clear and transparent to potential
contributors by documenting them in `docs/decisions`, starting with
the decision to use conventional commits.

Use the MADR format (https://adr.github.io/madr/).

docs/decisions/0001-use-conventional-commits.md

@@ -0,0 +1,68 @@
+# Use Conventional Commits
+
+## Context and Problem Statement
+
+* How to encourage PRs that focus on one issue?
+* How to reduce the burden on the person responsible for compiling the release notes?
+
+## Considered Options
+
+* Adopt [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+* Adopt another standard
+* Adopt a project-specific approach
+* Do nothing
+
+## Decision Outcome
+
+Chosen option: "Adopt Conventional Commits", because comes out best (see below).
+
+### Consequences
+
+* Good, because PRs are more focused
+* Good, because initial release notes are easier to produce
+* Bad, because contributors have to learn about Conventional Commits during their first PR
+
+## Pros and Cons of the Options
+
+### Adopt Conventional Commits
+
+To quote from https://www.conventionalcommits.org/en/v1.0.0/:
+
+> The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
+>
+> The commit message should be structured as follows:
+>
+> ```
+> <type>[optional scope]: <description>
+> [optional body]
+>
+> [optional footer(s)]
+> ```
+
+* Good, because straightforward to understand and describe
+* Good, because easy to write tooling for
+* Good, because tooling already exists
+   * To automatically validate PR titles during PR review
+   * To create initial changelogs or release notes
+* Bad, because contributors unaware with Conventional Commits need to learn about it
+
+### Adopt another standard
+
+There doesn't seem to be one in the open source world.
+
+### Adopt a project-specific approach
+
+Define our own standard and formatting for commit messages.
+
+* Bad, because it's unlikely we'd come up with anything better than Conventional Commits
+* Bad, because we'd have to write our own documentation
+* Bad, because we'd have to write our own tooling
+* Bad, because we can expect at least some contributors to already be familiar with Conventional Commits, they shouldn't have to learn our thing too
+
+### Do nothing
+
+Keep the status quo.
+
+* Good, because contributors do not need to do anything different
+* Bad, because contributors and reviewers can have different expectations of what is reasonable to include in a PR description, causing friction at review time
+* Bad, because it keeps the burden on the person responsible for maintaining release notes and changelogs is still high

docs/decisions/adr-template.md

@@ -0,0 +1,79 @@
+---
+# 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}
+---
+# {short title of solved problem and 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.}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Decision Drivers
+
+* {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)}.
+
+<!-- This is an optional element. Feel free to remove. -->
+### 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, …}
+* … <!-- numbers of consequences can vary -->
+
+<!-- This is an optional element. Feel free to remove. -->
+## Validation
+
+{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Pros and Cons of the Options
+
+### {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}
+<!-- use "neutral" if the given argument weights neither for good nor bad -->
+* Neutral, because {argument c}
+* 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}
+* …
+
+<!-- This is an optional element. Feel free to remove. -->
+## 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 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 here appear as well.}