Link Search Menu Expand Document (external link)

Architecture Decisions

Keep track of all major decisions that affect the architecture.

Adjust this pattern to your preferences. See: Architecture Decision Records </svg>

Table of contents

Summary

 Track the status and outcome of decisions that affect the architecture design.
When to use- For any architecture decision with major impact on the implementation.
- To support non-functional requirements of the software.
- To ensure consensus about architecture direction in the project team.
Participants- Person(s) investigating the decision.
- People affected by the decision (stakeholders).
Requirements- Decisions are preceded by a Spike to gather background information.
- Inform stakeholders, process their feedback, involve them in decision-making.
DurationAbout one hour to document the decision.
Expected outcomeAn architecture decision has been made.

➥ I need more info

Preparation

  1. Template: Determine the markdown template to use for your ADR’s.
    • Template should be lean. Lower the barrier of creation and maintenance work involved.
    • Template should be informative. Easy to parse by readers.
  2. Location: Determine the location where the template and all ADR’s are located.
    • Best: In the version-controlled codebase, e.g. in a /docs/adr folder.
    • Alternative: In the project’s Docs website if architecture is documented there.
  3. Tools: Configure tools to help support the ADR documentation procedure.
    • For example, Issue and PR templates, issue tags, specialized ADR tools </svg>
  4. Procedure: Document the procedure for creating ADR’s.
    • For example, in the project’s README.md or CONTRIBUTING.md or in the docs.

Usage guidelines

Following guidelines are helpful to consider:

  • ADR’s are brief, 1 to 2 pages.
  • ADR’s are listed on the project backlog / issue tracker.
  • ADR’s are reviewed before text is committed.
  • ADR’s are uniquely numbered (e.g. ADR 001).
  • ADR filenames are consistent, can be sorted (e.g. adr-001-track-architecture-decisions.md)

Procedure

This procedure assumes ADR creation is preceded by a Spike.

  1. Create an Issue in the project tracker of the repository affected by the decision.
    • Add the spike label.
    • Prefix title with ADR: followed by ADR Title.
    • Briefly describe the ADR Summary.
  2. Create a Pull Request based on the ADR Template.
    • Prefix the PR with WIP: as long as the Spike isn’t completed.
    • Reference the Spike issue in the PR description.
  3. Update information based on work done on the Spike.
    • Assign the Spike issue to the people in charge of elaborating.
    • Use the Spike issue as location for discussion, feedback collection.
    • Update the text of the ADR Pull Request as needed.
  4. Merge the ADR Pull Request when it passes review of affected stakeholders.
    • Merging the PR closes the Spike issue.
    • Update the ADR decision table with the outcome of the decision.

Variation: Pull Requests as Spikes

Step 1. and 2. can be combined, whereby the Pull Request becomes the Spike, instead of having a separate issue for it in the issue tracker. Beware when doing so, that the PR should be able to be tracked as-if part of the backlog, and allows for ongoing discussion to take place.

The Forgejo code forge supports this process, and Groundwork uses this variation as follows:

  • Top-level Architecture page in the Docs contains a table listing all ADR’s.
  • Individual ADR files are stored in /docs/adr in the Groundwork repository </svg>
  • ADR Pull Request is tracked on a Kanban board in the same repository.

← ↑ →