ADR Process#
Creating an ADR#
Every team member can create an ADR, but the team should establish a definition of ownership for an ADR. Each author is the owner of an ADR and is responsible for the maintenance and communication of the content of the ADR.
Other team members can always contribute to an ADR, but the owner has the final say on the content of the ADR and when this is ready to be proposed to the team for approval.
The following diagram illustrations the ADR creation process:
After the ADR is created, the author should propose it to the team for approval. The team should review the ADR and provide feedback. If the ADR is approved, it should be stored in the ADR repository and made accessible to all team members.
The ADR is stored in Git for tracking changes and versioning. The ADR repository should be organized in a way that makes it easy to find and reference ADRs. Each ADR should be stored in a separate file with a unique identifier.
Applying an ADR to a Decision or evaluation#
When a team member needs to make a decision that has architectural implications, they should consult the ADR repository to see if a relevant ADR already exists. If an ADR is found, the team member should review it to understand the context, decision, and consequences of the previous decision.
The following diagram illustrates the process of applying an ADR to a decision or evaluation:
As a good practice, each software change should go through peer reviews and require at least one approval. During the code review, a code reviewer might find changes that violate one or more ADRs. In this case, the reviewer asks the author of the code change to update the code, and shares a link to the ADR. When the author updates the code, it is approved by peer reviewers and merged into the main code base.
ADR review process#
The team should treat ADRs as immutable documents, after the teams accepts or rejects them. If an ADR needs to be updated, a new ADR should be created to replace the old one. The new ADR should reference the old ADR and explain the reasons for the change. The old ADR should be marked as superseded and should not be used for new decisions.
The following diagram illustrates the ADR review process:
