Amazon Web Services has published a guide for using architecture decision records (ADRs). They recommend a process to adopt and review ADRs in software engineering teams. The process results in a collection of approved, rejected, or superseded ADRs in a decision log.
AWS proposed this ADR process to facilitate architectural decision-making, avoid repetitive discussions about the same topics, and communicate decisions effectively.
An ADR is a short document that describes a team decision that influences the software architecture they are building. It includes the decision but also its context and consequences. A group of ADRs composes a decision log that provides a broad context, design information, and implementation details about the project or product.
The most common inputs for the ADR process are functional or non-functional requirements that need an architecturally significant decision. Any team member who identifies a decision like that should create an ADR. Using templates can simplify the ADR creation and ensure that it captures all the relevant information.
According to AWS, the team member who creates an ADR is also its owner and is responsible for maintaining and communicating its content. In the beginning, the ADR owner provides an ADR in "proposed" state, which means that it is ready for review. Then, the owner arranges a team meeting to review and decide if the ADR is accepted, requested for rework, or rejected.
If the team finds that the ADR needs improvement, it preserves the "proposed" state, and the owner and other team members work on the refinements. Otherwise, the ADR status changes to "accepted" or "rejected" and the ADR becomes immutable. If the team needs to update that decision, the team should propose a new ADR, and when this ADR is accepted, it supersedes the previous.
The following graph shows the ADR creation, ownership, and adoption process.
AWS recommends that ADRs should have a change history. Once an ADR is approved or rejected, it should be considered immutable. If the team accepts a new ADR that replaces or updates a previous decision, the ADR owner should change the state of the old ADR to "superseded". If the new ADR is rejected, no change to the old ADR is required.
The following graph shows the ADR update process.
The decision log will grow over time, and it will provide a history of all decisions taken by the team. For example, during code or architecture reviews, the team can use the decision log as a reference to validate if changes conform to agreed decisions or if they need to create a new ADR.
