Skip to content

Architecture Decision (AD) Guide

Jump to bottom
Greg Swindle edited this page Apr 27, 2019 · 1 revision

Architecture Decision (AD) Guide

An architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

Table of Contents

1. Definitions

Architecture Decision (AD)
A software design choice that addresses a significant functional or non-functional requirement.
Architecture Decision Record (ADR)
A document that captures an important architectural decision made⏤proposed, accepted, rejected, or deprecated and superseded by ${ADR-ID}⏤along with its context and consequences.
Architecture Decision Log (ADL)
The collection of all ADRs created and maintained for software products, as well as the teams and organizations that design, develop, assess, maintain, and distribute software products.
Architecturally-Significant Requirement (ASR)
A requirement that has a measurable effect on a software system's architecture.

2. Architecture Decision Workflows

Architecture Decision Records are resulting artifacts of community-driven, lightweight workflow.

2.1. Distribute Design Authority with Architecture Decision Records

graph TD

subgraph ADR Workflow
A(("start")) --> B(Significant requirement, challenge, or change)
B --> C("Create GitLab Issue (with the ADR Template)")
C --> D("Field Comments and Discussions")
D --> E("Vote (lazy consensus)")
E --> F{"Tally 👍  👎  reactions"}
F --> |"👍 majority 'accepted'"| G("Apply badge 'ADR accepted'")
F --> |"👎 majority 'rejected'"| H("Apply badge 'ADR rejected'")
G --> I
H --> I("Merge ADR into `master`")
I --> J(("stop"))
end
Loading

2.2. From ADR to ASR: Implementing and Enforcing Decisions

In many cases, the Architecture Decision will require:

  • Software changes, e.g., refactoring source code

  • Constraint enforcement, e.g., detect and prevent data-leakage before committing to source control.

graph TD

  subgraph ASR Workflow
  A(("start")) --> B("Create GitLab Issue (with 'Feature' Template)")
  B --> |Think about the consequences of the decision| C("Express consequences as Acceptance Criteria")
  C --> |Apply label 'help wanted'| D("Develop validation software ('Fitness Functions')")
  D --> E{"Test"}
  E --> |Pass| F("Deploy")
  E --> |Fail| D
  F --> G("Invoke Fitness Function as CI Job or Webhook")
  G --> H(("stop"))
  end
Loading

3. How to start using ADRs

To start using ADRs, talk with your teammates about these areas.

3.1. Identification

  • How urgent and how important is the AD?

  • Does it have to be made now, or can it wait until more is known?

  • Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification.

  • Ideally maintain a decision todo list that complements the product todo list.

3.2. Decision making

  • A number of decision making techniques exists, both general ones and software and software architecture specific ones, for instance, dialogue mapping.

  • Group decision making is an active research topic.

3.3. Documentation

  • Many templates and tools for decision capturing exist.

  • See agile communities, e.g. M. Nygard's ADRs.

  • See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne.

3.4. Enactment and Enforcement

  • ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, develop, and operate it.

  • Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices.

  • ADs also have to be (re-)considered when modernizing a software sytem in software evolution.

3.5. Sharing (optional)

  • Many ADs recur across projects.

  • Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy.

  • Group decision making is an active research topic.

3.6. Layout Consistency

  • Many templates and tools for decisison capturing exist.

  • See agile communities, e.g. M. Nygard's ADRs.

  • See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne.

3.7. Guidance

  • The steps above are adopted from the Wikipedia entry on Architectural Decision

  • A number of decision making techniques exists, both general ones and software and software architecture specific ones, for instance, dialogue mapping.

4. Tools to help you with ADRs

You can start using ADRs with tools any way you want.

4.1. Google Drive

If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet.

4.2. Project/Issue Tracker

If you like using project planning tools, such as Atlassian Jira, then you can use the tool's planning tracker.

4.3. Wikis

If you like using wikis, such as MediaWiki, then you can create an ADR wiki.

4.4. Version Control: Using Git for ADRs

If you like using git version control, then here is how we like to start using ADRs with git for a typical software project with source code.

  1. Create a directory for ADR files:

    mkdir adr

  2. For each ADR, create a text file, such as database.txt:

    vi database.txt

  3. Write anything you want in the ADR. See the templates in this repository for ideas.

  4. Commit the ADR to your git repo.

5. ADR Style Guidelines and Conventions

If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention.

5.1. File Name Conventions

5.1.1. Format

We follow the kebab-case format.

Examples:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

5.1.2. Syntax

Always use:

  • Present tense verbs

    Why:

    The name has a present tense imperative verb phrase. This helps readability and matches our commit message format.

  • Lowercase words separated by dashes

    Why:

    The name uses lowercase and dashes (just like this repo). This is a balance of readability, usability, SEO, and commit message consistency.

  • .md File Extension

    Why:

    The extension is markdown. Markdown renders consistently, and it's easy to read even as raw text.

5.2. File Content Conventions by Section

There are five (6) required sections in every ADR: Title, Decision date, Status, Context, Decision, and Consequences.

You may include an optional References section immediately following the Consequences section if you need to cite other works.

5.2.1. Title

  • Prefix the title with "Architecture Decision Record: "

    Why:

    This helps search engines index ADRs consistently, and it clearly identifies the purpose of each ADR in isolation.

  • Keep the File Name and Title Consistent

    How:

    If you named an ADR file

    format-timestamps.md

    then your Title section SHOULD read

    Architecture Decision Record: Format Timestamps

    Why:

    File names that differ from their titles are confusing, and SEO results rank higher when there is consistency.

5.2.2. Decision Date

...

5.2.3. Status

...

5.2.4. Context

...

5.2.5. Decision

...

5.2.6. Consequences

...

5.2.7. References and Attributions optional

...

6. Suggestions for writing good ADRs

6.1. General Characteristics

  1. Stateful: Identify when the AD was made using ISO8601 YYYY-MM-DD

  2. Rational Explain the reason for making the particular AD.

  3. Immutable: The decisions made in a previously published ADR should not be altered

  4. Specific: Each ADR should be about a single AD

6.2. Context

  1. Explain your organization's situation and business priorities

  2. Include rationale and considerations based on social and skills makeups of your teams

6.3. Consequences

  1. Right approach - "We need to start doing X instead of Y"

  2. Wrong approach - Do not explain the AD in terms of "Pros" and "Cons" of having made the particular AD

7. Changing Decisions: ADR Deprecation

A new ADR may take the place of a previous ADR when an AD is made that replaces or invalidates a previous ADR, a new ADR should be created.

8. ADR Sample Templates

ADR example templates that we have collected on the net:

9. More information

9.1. Justifications for ADRs

9.2. ADR Templates

9.3. In-depth Resources

9.4. Tools

9.5. Examples

9.6. See also

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBM’s e-Business Reference Architecture Framework

10. References and Attributions

GitLab Markdown | GitLab. (2019). Docs.gitlab.com. Retrieved 8 March 2019, from https://docs.gitlab.com/ee/user/markdown.html

This document is an adaptation of joelparkerhenderson/architecture_decision_record. (2019). GitHub. Retrieved 8 March 2019, from https://github.com/joelparkerhenderson/architecture_decision_record/blob/master/README.md#architecture-decision-record-adr

API

Public interface, with examples.

Rule

  1. ActivityRule
  2. Rule

RuleContext

  1. RuleContext
  2. Fact

RuleElement

  1. Operator
  2. Proposition
  3. Variable
    1. ArrayVariable
    2. DateVariable
    3. ErrorVariable
    4. InvalidRuleElementError
    5. MapVariable
    6. NumberVariable
    7. ObjectVariable
    8. SetVariable
    9. StringVariable
    10. SymbolVariable
    11. WeakMapVariable
    12. WeakSetVariable

RuleOverride

  1. RuleOverride

RuleSet

  1. RuleSet

Globals

  1. factory
  2. typeInspector
Clone this wiki locally