ADRsο
For core decisions we use Architecture Decision Records
. They are a type of RFC but smaller in scope and more
exact in the decision. The goal of adding an ADR is to summarize a discussion or fact-gathering effort. An RFC is the
start of a discussion and may occur before in-depth fact-finding occurs.
On the other hand, not every decision is an ADR. ADRs have to be significant. Things like naming, local APIs, or code structure rarely match this criteria. These may be better as open discussions or RFCs, which may not lead to an easily summarized conclusion. Instead, reach for an ADR when you can summarize the decision in a few sentences, at most. A good ADR should fit on the format βWhen doing β¦, we do β¦ because of β¦β.
An ADR should be written whenever a decision of significant impact is made; it is up to each team to align on what defines a significant impact.
ADR Processο
The ADR process is meant to be very fast, with few fixed steps.
Identify need for a decision
Write an ADR using the below template
Open a PR
Once PR is accepted and merged, implement the decision.
Templateο
# SEQUENCE_NUMBER. TITLE
Date: DATE WHEN PROPOSED
## Status
<!-- all ADRs start their life as accepted - we don't merge ADRs without accepting them. -->
Accepted
## Context
Describe when this decision would be relevant and why.
## Decision
An exact decision of what we will do when the context applies..
## Consequences
The end result of applying the decision.