Skip to content

Latest commit

 

History

History
48 lines (29 loc) · 1.39 KB

2022-07-21_adr.md

File metadata and controls

48 lines (29 loc) · 1.39 KB

Use ADRs committed to Git in markdown format

  • Status: proposed
  • Who: proposed by STO
  • When: proposed on 2022-07-21
  • Related: no related ADRs

Decision

Use ADRs as markdown files recording important stuff.

Commit the decisions to the Git repo they're relevant to, use markdown format.

Don't be precious about the format. KISS - to encourage creating ADRs and keeping them up to date.

Context

Architecural decisions often get lost. Sometimes they get documented in external locations (Wiki, Jira, documents, etc.) But those usually go out of date and often get lost (version or product changes, lost data, etc.)

The intent is to aid developerment consistency by providing a historical record of what decisions have been made and why.

Having a record of what was considered, what was not considered and who made the decisions also gives us more condifence in changing a decision when needed.

Also helps onboarding.

Consequences

Markdown is a bit limiting, but we shouldn't be putting that much complicated stuff in ADRs.

  • architecure decisions available publicly (instead of on private wiki)
  • security ADRs that have lots of context and consequences can act as a guide for attackers

Links