joelparkerhenderson / architecture-decision-record

Architecture decision record (ADR) An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences. Contents: • What is an architecture decision record? • How to start using ADRs • How to start using ADRs with tools • How to start using ADRs with git • File name conventions for ADRs • Suggestions for writing good ADRs • ADR example templates • Teamwork advice for ADRs • Teamwork questions for ADRs • Next step concepts for ADRs • Architecture diagrams \& views \& viewpoints • Fitness functions for decisions as code • Decision guardrails for pull requests • For more information Templates: • Decision record template by Jeff Tyree and Art Akerman • Decision record template by Michael Nygard • Decision record template by EdgeX • Decision record template by arc42 • Decision record template for Alexandrian pattern • Decision record template for business case • Decision record template of the MADR project • Decision record template using Planguage • Decision record template by Paulo Merson • Decision record template by Olaf Zimmermann • Decision record template by Gareth Morgan • Decision record template by GIG Cymru NHS Wales • Translations into more languages Examples: • CSS framework • Environment variable configuration • Metrics, monitors, alerts • Microsoft Azure DevOps • Monorepo vs multirepo • Programming languages • Secrets storage • Timestamp format • Many more... Translations into more languages What is an architecture decision record? An **architecture decision record** (ADR) is a document that captures an important architectural decision made along with its context and consequences. An **architecture decision** (AD) is a software design choice that addresses a significant requirement. An **architecture decision log** (ADL) is the collection of all ADRs created and maintained for a particular project (or organization). An **architecturally-significant requirement** (ASR) is a requirement that has a measurable effect on a software system’s architecture. All these are within the topic of **architecture knowledge management** (AKM). The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for more information. Abbreviations: • **AD**: architecture decision • **ADL**: architecture decision log • **ADR**: architecture decision record • **AKM**: architecture knowledge management • **ASR**: architecturally-significant requirement How to start using ADRs To start using ADRs, talk with your teammates about these areas. Decision identification: • How urgent and how important is the AD? • Does it have to be made now, or can it wait until more is known? • Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification. • Ideally maintain a decision todo list that complements the product todo list. Decision making: • A number of decision making techniques exist, both general ones and software architecture specific ones, for instance, dialogue mapping. • Group decision making is an active research topic. Decision enactment and enforcement: • ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, develop, and operate it. • Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices. • ADs also have to be (re-)considered when modernizing a software system in software evolution. Decision sharing (optional): • Many ADs recur across projects. • Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy. Decision documentation: • Many templates and tools for decision capturing exist. • See agile communities, e.g. M. Nygard's ADRs. • See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne. For more: • The steps above are adopted from the Wikipedia entry on Architectural Decision How to start using ADRs with tools You can start using ADRs with tools any way you want. For example: • If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet. • If you like use source code version control, such as git, then you can create a file for each ADR. • If you like using project planning tools, such as Atlassian Jira, then you can use the tool's planning tracker. • If you like using wikis, such as MediaWiki, then you can create an ADR wiki. How to start using ADRs with git If you like using git version control, then here is how we like to start using ADRs with git for a typical software project with source code. Create a directory for ADR files: For each ADR, create a text file, such as : Write anything you want in the ADR. See the templates in this repository for ideas. Commit the ADR to your git repo. File name conventions for ADRs If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention. We prefer to use a file name convention that has a specific format. Examples: • choose-database.md • format-timestamps.md • manage-passwords.md • handle-exceptions.md Our file name convention: • The name has a present tense imperative verb phrase. This helps readability and matches our commit message format. • The name uses lowercase and dashes (same as this repo). This is a balance of readability and system usability. • The extension is markdown. This can be useful for easy formatting. Suggestions for writing good ADRs Characteristics of a good ADR: • Rationale: Explain the reasons for doing the particular AD. This can include the context (see below), pros and cons of various potential choices, feature comparisons, cost/benefit discussions, and more. • Specific:…