Scribd
Upload
41 views9 pages

Architecture Decision Records in MD and GIT

The document discusses Architecture Decision Records (ADRs), which are logs that record architectural decisions and their rationale. ADRs follow a standard format that includes a title, context/problem statement, decision drivers, considered options, decision outcome, and consequences. They are typically written in Markdown format and stored in a source control system with unique IDs for each decision. Categories can optionally be used to group related ADRs together.

Uploaded by

marcosnj
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
41 views9 pages

Architecture Decision Records in MD and GIT

The document discusses Architecture Decision Records (ADRs), which are logs that record architectural decisions and their rationale. ADRs follow a standard format that includes a title, context/problem statement, decision drivers, considered options, decision outcome, and consequences. They are typically written in Markdown format and stored in a source control system with unique IDs for each decision. Categories can optionally be used to group related ADRs together.

Uploaded by

marcosnj
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 9

Architecture Decision

Record (ADR)

Record of a single architectural


decision and it’s rationale

# Title
## Context and Problem Statement
## Decision Drivers
## Considered Options
## Decision Outcome
## Consequences
## Validations
## Pros and Cons of the Options
- Example -

Use Dashes in Filenames

Context and Problem Statement


What is the pattern of the
filename where an ADR is stored?

Considered Options
• NNNN-title-with-dashes.md -
format used by adr-tools
• YYYY-MM-DD Title -
see https://github.com/joelparke
rhenderson/architecture_decisio
n_record#adr-file-name-
conventions
- Example –

Use Dashes in Filenames


Decision Outcome
Chosen option: "NNNN-title-with-
dashes.md", because
• NNNN provides a unique number,
which can be used for referencing in
the forms
• ADR-0001 in plain text and
• by @ADR(1) Java code (enabled by
e-adr)
• The creation time of an ADR is of
historical interest only, if it gets
updated somehow. The arguments are
similar than the ones by Does Git
have keyword expansion?
• Having no spaces in filenames eases
working in the command line
• This is exactly the format offered by
adr-tools
ADRs

Decision log, the collection of


decisions made in a project

docs
decisions
0000-use-markdown-any-decision-records.md
0001-use-CC0-or-MIT-as-license.md
0002-do-not-use-numbers-in-headings.md
0003-provide-own-madr-tools.md
0004-write-own-toc-tool.md
0005-use-dashes-in-filenames.md
0006-use-names-as-identifier.md
0007-do-not-emphasize-line-headings.md
0008-add-status-field.md
0009-support-links-between-adrs.md
0010-support-categories.md
0011-use-asterisk-as-list-marker.md
0012-use-curly-brackets-placeholder.md
0013-use-yaml-front-matter-for-meta-data.md
0014-allow-neutral-arguments.md
Support Categories

docs
decisions
backend
0000-use-dotnetcore.md
ui
0000-use-angular.md

Context and Problem Statement


The number of ADRs grows and
the context/topic/scope of ADRs
might be different (e.g., frontend,
backend)

Decision Drivers
• Easy to find groups ADRs in
hundreds of ADRs
• Easy to group
• Easy to create
…
- Example -

Use Markdown Any


Decision Records

Context and Problem Statement


We want to record any decisions
made in this project independent
whether decisions concern the
architecture ("architectural
decision record"), the code, or
other fields. Which format and
structure should these records
follow?
- Example -

Use Markdown Any


Decision Records

Considered Options
• MADR 3.0.0 – The Markdown
Any Decision Records
• Michael Nygard's template – The
first incarnation of the term
"ADR"
• Sustainable Architectural
Decisions – The Y-Statements
• Other templates listed at
https://github.com/joelparkerhe
nderson/architecture_decision_r
ecord
• Formless – No conventions for
file format and structure
- Example -

Use Markdown Any Decision


Records
Decision Outcome
Chosen option: "MADR 3.0.0", 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.
• MADR allows for structured
capturing of any decision.
• The MADR format is lean and fits
our development style.
• The MADR structure is
comprehensible and facilitates usage
& maintenance.
• The MADR project is vivid.
Conclusion
ADRs, or Architecture Decision Records,
are logs of decisions and their rationale.

Pros:
• conscious decision making
• understanding the context and
trade-offs
• accountability and openness
• highlights architectural weak spots
• easier start for new hires

How?
• Markdown
#Title #Context #Decision #Choices
• Source control
• docs/decisions/0001-this-is-title1.md
• docs/decisions/0002-this-is-title2.md
• Categories (optional)
• docs/decisions/backend
• docs/decisions/ui

You might also like