Start using Architecture Decision Records (ADRs) in Sourcegraph. (!34511) · Merge requests · Administrator / sourcegraph

Administrator requested to merge mv/arch/adrs into main Apr 26, 2022

Created by: vrto

Description

Start using Architecture Decision Records (ADRs).

Context

Explained in the ADR file.

Format

Loosely inspired by the one from Michael Nygard. I've slightly modified it and dropped the Status section, as it felt like that conflicted with RFCs (RFCs help us to come up with decisions, ADRs will help us log them).

There are other, more sophisticated templates that we could migrate to if we felt like the current one doesn't do a good job.

Structure

This is an example structure I propose to follow.

doc/adr
├── 0001-record-architecture-decisions.md
├── 0002-foo-bar.md
└── 0003-some-decision.md

Tooling

Flat files (markdown), nothing fancy.

There are existing supporting tools, such as adr-tools, but my recommendation is to hand-write a few and create sg adr later on (once we're happy with how things are going).

Test plan

None, this is just documentation.

Start using Architecture Decision Records (ADRs) in Sourcegraph.