Working with ADRs

As decided in ADR 0001 - Architecture Decision Records, we use ADRs. This page helps to work with ADRs.

Creating a new ADR

You need Cookiecutter to use the provided templates and it’s highly recommended to have pre-commit ready and the Git hooks installed with pre-commit install.

  1. Run cookiecutter templates in the root directory of the cloned documentation repository

  2. Fill in the missing pieces (ADR number should automatically be the next free)

  3. Edit the ADR in the created file

ADR Index

The ADR index at docs/modules/ROOT/pages/adr/index.adoc is automatically generated in a Git pre-commit hook, which calls hack/adr-tool.py generate.

Related Links

We’re not the only ones using ADRs, here’s a collection of interesting readings: