Lullabot's Architecture Decisions

Definition and purpose

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log.

An ADR is immutable once accepted, beyond simple fixes and improvements that don't change the substance of the decision. Otherwise, only its status can change (i.e., become deprecated or superseded). That way, team members can become familiar with the whole history of decisions just by reading its decision log in chronological order. Moreover, maintaining this documentation aims at:

• 🚀 Improving and speeding up the onboarding of a new team member
• 🔭 Avoiding blind acceptance/reversal of a past decision (cf Michael Nygard’s famous article on ADRs)
• 🤝 Formalizing the decision process of the team

Project-Specific Architecture Decision Records

For individual client projects at Lullabot, or more complicated open-source projects, we expect that creating ADRs to describe key decisions will be worthwhile. We will evaluate project-specific ADRs periodically to determine if they can be generalized to all Lullabot projects.

Write a project-specific ADR when:

1. Writing significant custom code code, such as entirely new Drupal modules, to support a client request. Describe why new code was needed, and what alternatives were considered.
2. When writing "glue" code that makes two normally unrelated parts of a code base interact.
3. When a major overall architectural decision has been reached, such as:
   • Choosing a page-building paradigm (e.g. documenting what forces led to the selection of layout builder vs. paragraphs vs entity embeds in CKEditor).
   • Approach to content referencing (e.g. which direction do our references go, specific use of views to limit referenceable entities, use of Entity Browser vs. Media Library for media selection, and why)
   • Patterns for how theme templates are included, especially where an external pattern library is integrated to a Drupal theme.
   • Decisions about how content types, media, display modes and theme-level templates interact.
   • Selection of one or more methods for data migration or imports

Create ADRs for a project inside of the Git repository of the project, in a folder like docs/adr. Try to avoid using external wikis or systems like Confluence, as they make code-related documentation changes harder to track. However, if a client requires you to use a wiki, that’s better than no ADRs at all.

License and Contributions

Lullabot is making these records publicly available as a reference for our clients and in the hope that community members find them useful in their work. While others are free to copy and adapt these decisions according to the Creative Commons Attribution 4.0 license, these records represent how Lullabot distinctly approaches projects. Since that requires direct knowledge of our work, we are not accepting outside contributions. Use our contact form or social media to report errors and omissions. As well, please consider applying to work at Lullabot if you are interested in contributing more directly!

You can download the source of our ADRs as an archive of MD files.

This work is licensed under a Creative Commons Attribution 4.0 International License.