# Resolve to use ADRs (following MADR style) to track Architecturally Significant Requirements in this repository

* Status: accepted
* Deciders: Scott
* Date: 2024-03-28

## Context and Problem Statement

In the interest of tracking our architectural decisions, we're adopting this low-effort method for tracking our decisions based on ASRs (Architecturally Significant Requirements).

See https://verses.atlassian.net/wiki/spaces/Architecture/pages/634748987/VERSES+Architecture+Best+Practices for more details.

## Decision Drivers

* we need a way to record the decisions that we made so that we can quickly understand why things were done and reason about additional changes

## Considered Options

1) wiki page (E.g. a wiki page that just lists decisions)
2) a less structured log in the repo (e.g. autogenerated changelog, a single file, or freeform)
3) non-MADR ADRs (e.g. something like those outlined on [adr.github.io](https://adr.github.io) (excluding MADR))
4) MADR ADRs (as outlined in [adr.github.io/madr](https://adr.github.io/madr/))

## Decision Outcome

Chosen option: "option 4", because it is (somewhat) standardized, is close to the code, and meets our needs.

### Positive Consequences

* ASRs force thinking about the decision and how to communicate it
* easily record ASRs
* easily find and understand architectural decisions
* close to code
* easily discoverable

### Negative Consequences

* a little extra time to ship a feature (may be experienced by an engineer but is overall actually a positive)

## Pros and Cons of the Options

### Option 1: a wiki page

#### a wiki page is good, because it's
* Good, because it's publicly visible

#### a wiki page is bad, because it's
* distant from code: hard to keep up to date
* hard to have a real review/ change management process around it

### Option 2: a less structured log in the repo

#### a less structured log in the repo is good, because it's
* publicly visible
* closer to the code
* under change management

#### a less structured log in the repo is bad, because it's
* hard to grok (especially across teams)
* tricky to parse if not built mindfully
* may not contain the info needed

### Option 3: non-MADR ADRs

#### non-MADR ADRs is good, because they're
* publicly visible
* closer to the code
* under change management
* easier to read than options 1 and 2
* contains relevant info

#### non-MADR ADRs is bad, because they're
* not as easy to grok across teams

### Option 4: MADR ADRs

#### MADR ADRs are good, because they're
* publicly visible
* closer to the code
* under change management
* easiest to read
* contain relevant info
* easiest to grok across teams

#### MADR ADRs are bad, because