ADR-0001: Use of Architecture Decision Records
Date: 2024-09-30
Status
Proposed
| Status | Date | Author |
|---|---|---|
| Proposed | 2024-09-30 | Iskander Sierra |
Context
The architecture of a software system is a set of decisions that are made to achieve the desired quality attributes of the system. These decisions are made by the architects, developers, and other stakeholders of the system. The architecture of a system is a living entity that evolves over time as the system grows and changes. It is important to document the architecture decisions that are made so that they can be reviewed, communicated, and understood by all stakeholders.
Decision
Architecture Decision Records (ADRs) will be used to document the architecture decisions that are made for the system. An ADR is a document that captures an important architectural decision that needs to be made or has been made.
The documents will be stored in the architecture/adr directory of the project repository. Each ADR will be a markdown file with a unique number and a descriptive title and with a consistent structure.
The ADR should include the following information:
- Title: A short, descriptive title for the decision.
- Date: The date when the decision was made.
- Status: The current status of the decision (e.g., proposed, accepted, rejected).
- Status log: A log of the status changes of the decision and the dates and authors of those changes.
- Context: The context in which the decision was made, including the problem that needed to be solved and the constraints that needed to be considered.
- Decision: The decision that was made, including the rationale behind the decision and any alternatives that were considered.
- Any relevant diagrams and code snippets should be included. To create diagrams, a combination of tools like the following can be used, as long as once pushed to git, they can be rendered as images (png, jpg, svg, etc.) in the documentation:
- Excalidraw,
- Mermaid,
- Draw.io,
- PlantUML or
- d2
- Any relevant diagrams and code snippets should be included. To create diagrams, a combination of tools like the following can be used, as long as once pushed to git, they can be rendered as images (png, jpg, svg, etc.) in the documentation:
- Consequences: The consequences of the decision, including any trade-offs that were made and any risks that were identified.
- Others: Any other relevant information that should be included, like Pros and Cons, References, etc.
The current document is an example of an ADR that documents the decision to use ADRs to document the architecture decisions for the system. A bit of recurrence, isn’t it?
References
- Documenting Architecture Decisions by Michael Nygard: A blog post by Michael Nygard that introduces the concept of Architecture Decision Records.
- Architectural Decision Records: The official website for Architecture Decision Records.
- Sustainable Architectural Design Decisions: An article on InfoQ that discusses the importance of documenting architecture decisions.
- ADR Templates: A repository with templates for Architecture Decision Records.
Consequences
Pros
- The architecture decisions that are made for the system will be well-documented and can be reviewed, communicated, and understood by all stakeholders.
- Easy to create a historical record of the decisions that were made and the reasons behind those decisions.
- Useful for new team members who join the project and need to understand the architecture of the system.
- Easy to copy and paste the structure of the ADRs to create new ones.
Cons
- Requires discipline to create and maintain the ADRs on each architecturally significant decision.
- The ADRs can become outdated if not maintained properly.
- The ADRs can become a bottleneck if too many decisions need to be documented.
- The ADRs can become too verbose if not kept concise and to the point.