adr.github.io Documentation

Several tools support multiple templates or general ADR management workflows:

• ADG (Architectural Decision Guidance): A Go-based CLI for modeling and managing decisions. Supports Nygard, MADR (basic), and QOC templates.
• dotnet-adr: A cross-platform .NET Global Tool for ADR management.
• ReflectRally: A collaborative web application for structured ADR workflows, including ownership and review processes.
• adr.zone: A web-based generator supporting Nygard, MADR, Y-Statement, and ISO/IEC/IEEE 42010-inspired formats. It also provides a simple API for generation.

Beyond simple record keeping, these tools help manage and visualize software architecture:

• ArchUnit: Provides unit testing capabilities for architecture.
• docToolchain: Implements a 'docs-as-code' approach for software architecture with automation.
• Structurizr: A suite of tools for visualizing and exploring architecture using the C4 model.

An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software or hardware system.

An Architectural Decision Record (ADR) is a document that captures a single AD and its rationale. ADRs help teams understand the reasons behind a chosen architectural decision, including its trade-offs and consequences. A collection of these records maintained within a project is referred to as a decision log.

While primarily used for architecture, the concept of ADRs can be extended to any decision record used for design or other significant project choices.

To decide when an Architectural Decision should be marked as "done", evaluate it against the following five criteria (often referred to as the ecADR framework, focusing on the 'D' for Done):

1. Evidence: Sufficient data or reasoning is present.
2. Criteria and Alternatives: The decision is weighed against specific criteria and alternative options.
3. Agreement: Stakeholders have reached a consensus.
4. Documentation: The decision is formally recorded.
5. Realization/Review Plan: There is a plan to implement and subsequently review the decision.

You can embed architectural decisions directly into your source code using annotations:

• (Java) Embedded Architectural Decision Records: Uses ADR annotations to allow a distributed ADR log to be embedded within Java code.

This repository is based on the Chirpy theme. To pull in updates from the original Chirpy starter repository, add it as a remote and merge the changes into your local branch.

git remote add chirpy-starter git@github.com:cotes2020/chirpy-starter.git
git fetch chirpy-starter
git merge chirpy-starter/main

MADR is a template focused on architectural decisions that matter, emphasizing tradeoff analysis. It includes metadata such as decision makers and confirmation in addition to decision status.

To use MADR, you can populate the template in any text editor without specialized software. There are two main versions available:

• Full template: Comprehensive version.
• Minimal template: A stripped-down version.

Both versions are available in annotated (with guidance) and bare (clean) formats.

Tools for MADR include:

• A VS Code extension (note: may be outdated).
• Various other tools listed in the adr-tooling documentation.

The Nygard ADR format, based on the work by Michael Nygard, follows a specific lightweight structure suitable for Markdown. An ADR using this template must consist of the following five sections:

1. Title
2. Status
3. Context (describing the forces at play: technological, political, social, or project-local)
4. Decision
5. Consequences

You can run the Jekyll development server inside a Docker container using the Microsoft Jekyll devcontainer image. This avoids the need for local Ruby/Jekyll installation.

Note: Ensure you replace the volume mount path with your actual local repository path.

# 1. Start the container (replace the local path with your actual path)
docker run --rm -it -p 4000:4000 -v "C:\git-repositories\adr.github.io\adr.github.io:/tmp/adr" mcr.microsoft.com/devcontainers/jekyll:2-bullseye /bin/bash

# 2. Inside the container, install dependencies
gem install bundler && bundle install

# 3. Start the Jekyll server
bundle exec jekyll serve -H 0.0.0.0 -t

# 4. Access the site at http://localhost:4000/

The Y-statement is a lightweight template for capturing architectural decisions. It can be used in a short form or a long form.

Short Form

In the context of <use case/user story>, facing <concern> we decided for <option> to achieve <quality>, accepting <downside>.

Long Form

Includes an additional "because" section for rationale:

In the context of <use case/user story>, facing <concern>, we decided for <option> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside/undesired consequences>, because <additional rationale>.