Use Markdown Architectural Decision Records

Jun 3, 2023


Daniel Mackay [SSW]


Context and Problem Statement

We want to record architectural decisions made in this project. Which format and structure should these records follow?

Considered Options

Decision Outcome

Chosen option: "MADR 2.1.2 with Log4brains patch", because

  • Implicit assumptions should be made explicit. Design documentation is important to enable people understanding the decisions later on. See also A rational design process: How and why to fake it.
  • The MADR format is lean and fits our development style.
  • The MADR structure is comprehensible and facilitates usage & maintenance.
  • The MADR project is vivid.
  • Version 2.1.2 is the latest one available when starting to document ADRs.
  • The Log4brains patch adds more features, like tags.

The "Log4brains patch" performs the following modifications to the original template:

  • Change the ADR filenames format (NNN-adr-name becomes YYYYMMDD-adr-name), to avoid conflicts during Git merges.
  • Add a draft status, to enable collaborative writing.
  • Add a Tags field.