How to maintain architecture decision records
What does an architecture decision record cover?
An Architectural Decision Record (ADR) records a single architecturally significant decision and its rationale. The GitHub adr organization defines an architectural decision as a justified design choice that addresses an architecturally significant functional or nonfunctional requirement. The collection of ADRs created and maintained in a project is called a decision log.
According to AWS Prescriptive Guidance, an ADR explains a choice the team has made about a significant aspect of the software architecture it plans to build. The record contains the decision itself, its context, and its consequences. Records have statuses, and each record goes through a lifecycle.
The Microsoft Azure Well-Architected Framework says to record choices that affect the structure or fundamental quality attributes of a system or are difficult to reverse. The records also include alternatives that were ruled out. Requirements and constraints are recorded alongside the effects of the decision.
AWS includes structure, nonfunctional requirements, dependencies, interfaces, and construction techniques within the scope of architecturally significant decisions. Security, high availability, and fault tolerance are examples it gives of nonfunctional requirements. Coupling between components is an example of a dependency; APIs and published contracts are examples of interfaces. Libraries, frameworks, tools, and processes also fall under construction techniques.
According to AWS, functional and nonfunctional requirements are common inputs to the ADR process. When a team identifies the need for an ADR, one team member starts writing the record using a template used across the project. The template makes it easier to create records and ensures that relevant information is recorded.
AWS states that the decision log provides detailed information about implementation and design as well as the project context. Project members review ADR titles to get an overview of the context. They read the contents of the records to understand implementation and design choices in greater detail.
The contents of a record
AWS requires every ADR to describe at least the context of the decision, the decision itself, and the consequences of the decision for the project and its deliverables. The ADR structure focuses on why the team made the decision rather than how it implemented it.
Microsoft Azure recommends designing a template so that records follow the same structure. The common fields it recommends include a problem statement containing the context, the options considered, and the outcome of the decision. Important trade-offs, the level of confidence in the decision, and the record status are also parts of this structure.
According to Martin Fowler, the rationale should summarize the problem that made the decision necessary and the trade-offs considered. Alternatives that were seriously considered can be listed explicitly, with their pros and cons. Consequences are sometimes apparent from the rationale; at other times, they are stated explicitly in a separate section.
Fowler states that decisions are made under some degree of uncertainty and that the level of confidence can be recorded. The same section can also specify changes in the product context that would require the team to reconsider the decision. Microsoft Azure also says that recording the low level of confidence in an architecturally significant decision made with low confidence can be useful for future reassessments.
Microsoft Azure states that the consequences of decisions should not be hidden. Context and rationale should also appear in every record. Without the rationale, it becomes difficult for stakeholders to assess whether the decision is still valid when circumstances change.
If a decision will lead to multiple stages, such as short-, medium-, and long-term approaches, Microsoft Azure says to maintain each stage as a separate decision record. The same approach calls for records to be brief, focused, and factual. The ADR is not turned into a design guide; although links to additional rationale or design work can be provided, the decision itself should be clear without that additional material.
Fowler explains that writing an ADR serves to clarify thinking as well as create a record of the decision. Different views can emerge and be discussed during the group writing process. In the Advice Process Fowler describes, the input received while preparing the ADR is also included in the record. If the record is to be kept brief, the input can be summarized in the ADR and the full record kept separately.
Files and statuses
Fowler writes that a common approach is to keep ADRs in the source repository of the relevant codebase. One common location is the doc/adr directory. Using a lightweight markup language such as Markdown allows records to be read like code and the differences between them to be seen. A build task can also be used to publish the records on the product team's website.
According to Fowler, each record should be a separate file. Including an ascending sequence number and a name describing the decision in the filename makes the records easier to read in the directory listing. The most important content appears at the beginning of the record, with details later. Fowler recommends keeping records brief and direct and linking to supporting material when available.
In Fowler's status definitions, a record under discussion has the status Proposed. When the team accepts it and the decision is in effect, the status becomes Accepted. When the decision is significantly changed or replaced by another decision, the status becomes Superseded; the record contains a link to the ADR that replaces it.
Microsoft Azure states that status information keeps the current status of each decision clear, especially as the number of decisions grows. The status examples Azure gives are Proposed, Accepted, and Superseded. Status can appear in a consistent form in the template alongside context and options.
Microsoft Azure says to maintain the decision log as an append-only record. Accepted records are not revisited and edited. If a decision changes, a new record is written to replace the old one, and the two records are linked. This keeps the history of the thinking and when and why the direction changed visible.
How does team review proceed?
In the AWS process, any team member can create an ADR. The team defines what ownership means for each ADR. The record owner actively maintains and communicates its contents; other team members can also contribute to the record. If the contents change before the record is accepted, the owner approves those changes.
After the team identifies the architectural decision and its owner, the owner submits the ADR with the status Proposed. A record in this status is ready for review. The owner starts the review process; its purpose is to decide whether the team will accept the ADR, whether rework is needed, or whether the record will be rejected.
According to AWS, the project team, including the record owner, reviews the ADR. The meeting begins with time set aside to read the record. During this time, team members add comments and questions to flag points that are unclear. The record owner then reads each comment and discusses it with the team.
If the team identifies work to improve the record, the ADR remains in the Proposed status. The record owner defines the work and, together with the team, assigns an owner to each item. Team members can contribute to and resolve these items. The record owner is responsible for rescheduling the review.
If the team rejects the ADR, the owner adds the reason for rejection to prevent future discussions on the same topic and changes the status to Rejected. If the team approves the ADR, the owner adds the list of stakeholders and changes the status to Accepted.
AWS says the team should use ADRs as references in code and architecture reviews whenever possible. If a code review finds that a change conflicts with one or more ADRs, the reviewer asks the author of the change to update the code and shares a link to the relevant ADR.
When a record changes and the limits of the approach
AWS requires accepted or rejected ADRs to be considered immutable. To change an existing decision, a new ADR is created; the new record is reviewed and approved. When the new ADR is approved, the owner of the old record changes its status to Superseded.
Fowler states that keeping ADRs in the product repository will not work for decisions that span an ecosystem broader than a single codebase. Some people also think that keeping records in git makes them too difficult for non-developers to work with.
According to Microsoft Azure, an ADR is started at the beginning of a workload and maintained throughout the workload's life. An ADR is also started for an existing workload; if data about past decisions is available, records are created retrospectively based on known decisions. Beyond the initial design, the decision record also covers design directions relating to future functional and nonfunctional requirements.