Starter architectural decisions document.

ADR

Use of ADRs to track Architectural Decisions
============================================

Context
-------

At the moment architectural decisions are being made when required and they
are not recorded.

Decision
--------

Adopt
[ADR](https://github.com/joelparkerhenderson/architecture_decision_record)
records into the project. This file is an ADR. It describes the problem we are
facing, and the decision which was made in order to solve it.

ADR files are to be stored in `/arch`. Each file is in **markdown** format,
contains a title and has four sections **Context**, **Decision**,
**Consequences** and **Alternatives**:

- **Context**: Describe the nature of the problem
- **Decision**: Describe the decision that was made to solve this problem.
- **Consequences**: Describe any possible consequences to this decision.
- **Alternatives**: (optional) Other solutions which were considered, why they were rejected etc.

The ADR should be submitted as a PR either with the pull request where the decision
was (first) implemented or on it's own.

Each ADR should have an index superior to the last ADR and previous ADRs can
be contradicted by a later ADR. (e.g. `0000-introduce-adr.md`,
`0001-something-interesting`, `...`.

An ADR _MAY_ be created retroactively, although in general they _should_ be
ordered chronologically.

Consequences
------------

Having an ADR policy will enable future developers (and ourselves) to better
understand why decisions were made and therefore provide a better context for
making further decisions.

Creating an ADR also forces us to explain to _ourselves_ and the team why we
are making decisions, this can be especially useful when the ADR is part of a
pull request implementing a decision.

Finally, it provides a useful historical record of the project.