When they are working on a new feature, project leaders—whether open or closed source—need to decide how to implement it. Agile projects often make decisions on the fly, unlike the old waterfall world, where a long requirement-engineering phase precedes the development process. Often enough, the why and how of the feature are kept in the decision-making developer's brain. Newcomers to the project then are left to wonder why certain things are done in a certain way, making it hard for them to figure out and contribute, as the necessary knowledge is not readily available.
Michael Nygard identified this issue back in 2011 in his article Documenting architecture decisions, where he presents the concept of architecture decision records (ADRs).

The need for such records increases for larger or more distributed projects, especially those where no single architect is available or where new contributors are being onboarded. The time was ripe for such a format when Nygard wrote his article, and seven years later, IT consultancy Thoughtworks put ADRs into the Adopt category of its technology radar.
As the name ADR suggests, you use these records for making larger architectural decisions. They don't serve as a glorified change log or replace (good) commit messages.
Components of an ADR
This image shows the general components of an ADR:

- Number/Date: A unique increasing number and date that usually follows the ADR-nnnn pattern to help sort them from old to new
- Title: Indicates the content
- Context (Why): Describes the current situation and why you made this decision or thought it necessary—some variations explicitly break out an "alternatives covered" section to ensure all considerations get recorded
- Decision (What/How): Describes the what and how of the feature
- Status: Describes the status; note that ADRs can be superseded later by newer ADRs
- Consequences: Describes the effect of the decision, listing positive and negative aspects
While decision records contain the "technical" decisions, they should also list non-functional ones. They can also include the decision to use an ADR in the first place or the license chosen. You can find an example of this in the Operate First project's repository.
ADR formats
The previous section describes the basic format of an ADR. Over time, many ADR formats and templates have evolved. The ADR repository on GitHub lists some of them and some templates. Common to all is using a (lightweight) markup language like AsciiDoc.
Much more important than the concrete format you choose is where you put the records. It is best to put them next to the source code in your project in a dedicated ADR folder in the documentation. Of course, that isn't possible for projects with multiple repositories. There, the best option is to use the main repository and link it into the README of the dependent projects.
ODF and ADR
The Open Decision Framework (ODF) is a framework for making decisions openly and inclusively. Using ODF for minor projects may be overkill, but once your project targets multiple stakeholders and parties, ODF becomes a powerful tool.
Interestingly, the group of people likely to use ODF are the same people who benefit from ADRs. In fact, ODF encourages sharing decisions made openly. And ADRs can be a powerful way of doing so.

Wrap up
You can use ADRs during the ODF feedback loop: Put a draft of the decision with documentation of constraints, goals, and such into a pull request, and then update this alongside the feedback rounds. Once you make your decision, you can merge the pull request into the main repository.
For more information, read:
About the author
Heiko is a long-time open source committer. He currently works for Red Hat on the topic of monitoring and management of server and software systems. Heiko has received a master's in Computer Science from the University of Karlsruhe and has written two books on JBoss AS and Enterprise Java Beans.
Browse by channel
Automation
The latest on IT automation for tech, teams, and environments
Artificial intelligence
Updates on the platforms that free customers to run AI workloads anywhere
Open hybrid cloud
Explore how we build a more flexible future with hybrid cloud
Security
The latest on how we reduce risks across environments and technologies
Edge computing
Updates on the platforms that simplify operations at the edge
Infrastructure
The latest on the world’s leading enterprise Linux platform
Applications
Inside our solutions to the toughest application challenges
Original shows
Entertaining stories from the makers and leaders in enterprise tech
Products
- Red Hat Enterprise Linux
- Red Hat OpenShift
- Red Hat Ansible Automation Platform
- Cloud services
- See all products
Tools
- Training and certification
- My account
- Customer support
- Developer resources
- Find a partner
- Red Hat Ecosystem Catalog
- Red Hat value calculator
- Documentation
Try, buy, & sell
Communicate
About Red Hat
We’re the world’s leading provider of enterprise open source solutions—including Linux, cloud, container, and Kubernetes. We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.
Select a language
Red Hat legal and privacy links
- About Red Hat
- Jobs
- Events
- Locations
- Contact Red Hat
- Red Hat Blog
- Diversity, equity, and inclusion
- Cool Stuff Store
- Red Hat Summit