Skip to content

Latest commit

 

History

History
56 lines (30 loc) · 2.5 KB

0000-adrs.md

File metadata and controls

56 lines (30 loc) · 2.5 KB
Raw

0000 - Maintain Architectural Decision Records (ADRs)

Status

Accepted

Context

We feel a need to record important decisions, so that future colleagues can refer back to the rationale behind them. We feel a need to do this in a consistent, easy-to-discover, and lightweight but comprehensive manner.

Decision

We will record decisions about architecture and other important decisions next to the sourcecode in this repository.

There shall be a single hidden folder .adr at the top level of the repository.

ADRs are numbered by the order in which they were committed**, not by the order in which they were decided. An ADR with a greater number overrides an ADR with a lesser number.

Meta-(ADRs) are encouraged.** A meta-ADR records a decision about the ADR process itself -- such as a decision about the format, length or style of ADRs. This ADR is a meta ADR.

The format of an ADR shall follow the template by Michael Nygard** following the suggestion of Joel Parker Henderson:

# Decision record template by Michael Nygard

This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files.

In each ADR file, write these sections:

# Title

## Status

What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

## Context

What is the issue that we're seeing that is motivating this decision or change?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?

Consequences

The approach above provides an easily discoverable reference for developers in the future who question why the code is as it is. Being located in a single folder at the top level allows each ADR to "attach" to multiple files and folders.

There is no burden to make an ADR unless the maintainers of this repository deem it prudent.

It should reduce the chance of oscillating between multiple solutions to the same problem, or recommitting the same mistakes we have made in the past. Further motivation is provided in this blog post.