All ADRs

  • 4 deciders

    front-end, accessibility, performance

    Decided on

    Using SVGs for icons has the best display, performance, and accessibility

  • 5 deciders

    drupal, editorial-experience

    Decided on

    Placeholder text introduces significant usability and accessibility issues and should be avoided.

  • 5 deciders

    drupal, editorial-experience

    Decided on

    When content types have dedicated pages, matching the display order makes edit forms easier to understand.

  • 5 deciders

    javascript, front-end, performance

    Decided on

    Loading JavaScript as deferred has the best default performance

  • 5 deciders

    drush, deployments

    Decided on

    When updating Drupal code and configuration in a given environment, it's useful to make sure all members of the team and all teams follow a consistent set of steps, in the same order. Having consistent steps across multiple projects will reduce onboarding for new team members.

  • 4 deciders

    javascript, front-end, performance

    Decided on

    Loading JavaScript as async & deferred has the best default performance

  • 7 deciders

    drupal, code quality

    Decided on

    Wrapping the business logic for an entity using Typed Entity produces code that is easier to read, maintain, test, and discover.

  • 10 deciders

    drupal

    Decided on

    Rendering entities using view modes have multiple benefits. These include better maintainability, faster initial development time, better performance, and hardened security.

  • 10 deciders

    git

    Decided on

    Omitting key information in branch names can cause confusion over the purpose of a branch.

  • 3 deciders

    drupal, devops

    Decided on

    Using memory caches like Memcached or Redis in production but not in development environments can lead to bugs and confusion.

  • 4 deciders

    front-end, javascript

    Decided on

    Opt in to settings that raise errors for problematic code.

  • 5 deciders

    front-end, css

    Decided on

    Organizing CSS within projects the same way Drupal organizes its CSS establishes a consistent pattern.

  • 9 deciders

    javascript, front-end, back-end, developer-experience

    Decided on

    Strictly typed languages like TypeScript avoid unexpected behavior, prevent bugs, and improve code maintainability.

  • 6 deciders

    drupal, node-form, editorial-experience, performance, seo

    Decided on

    The metatag field makes the node form slow and overly complex for editorial users.

  • 5 deciders

    front-end, css, multilingual

    Decided on

    Decoupling styles from a language's writing direction makes them easier to maintain across translations.

  • 2 deciders

    meta

    Decided on

    We need a site generator to publish our ADRs.

  • 9 deciders

    drupal, editorial-experience

    Decided on

    Claro offers a modern, responsive, and accessible interface that showcases Drupal's capabilities from the outset.

  • 6 deciders

    diversity-inclusion

    Decided on

    Inclusive language can make technical subjects more inviting and understandable.

  • 6 deciders

    drupal, contrib-modules, editorial-experience

    Decided on

    Drupal's editorial experience in the "Add Content" page is confusing out of the box, especially when the content model's complexity increases.

  • 5 deciders

    drupal, contrib-modules, editorial-experience

    Decided on

    Drupal core by default outputs the maximum number of values (cardinality) as empty elements on entity forms, which usually represents a poor user-experience.

  • 6 deciders

    drupal, composer, php

    Decided on

    Allowing builds to succeed with failed patches can lead to malformed code or hidden errors.

  • 7 deciders

    drupal, php, composer

    Decided on

    When using cweagans/composer-patches, it is important that patch sources are consistent and do not change between builds.

  • 7 deciders

    drupal, php, composer

    Decided on

    Validating a complete Composer configuration is important to ensuring build issues are caught early.

  • 6 deciders

    drupal, php, composer

    Decided on

    Drupal's git repository has a different directory structure than projects built on Drupal. Default Composer Patches settings can cause Drupal patches to be silently misapplied.

  • 6 deciders

    devops

    Decided on

    Service integrations that use personal accounts tie the function of the service with the person's engagement with the project.

  • 4 deciders

    drupal

    Decided on

    When content translation is enabled, it's possible to decide which fields can be translated.

  • 2 deciders

    drupal

    Decided on

    Editors new to Drupal often try to translate content by changing the language on existing content, causing confusion for site visitors.

  • 6 deciders

    drupal

    Decided on

    Adopting a consistent set of rules when naming entities in Drupal can reduce errors and improve maintainability.

  • 6 deciders

    drupal, php, composer

    Decided on

    Default composer-patches settings can lead to misapplied patches or hidden errors. Using a consistent configuration across projects will reduce errors and save time.

  • 5 deciders

    drupal, php, coding, testing

    Decided on

  • 7 deciders

    drupal, security

    Decided on

    The first user account in a Drupal site (often referred to as "administrator" or "user 1") is granted every permission automatically. If the account credentials are compromised, an attacker can easily inject JavaScript to attack site visitors and can likely execute arbitrary PHP code.

  • 2 deciders

    drupal, php, coding

    Decided on

    Following stricter typing where available can significantly reduce bugs, and simplify maintainability. This has been proven by several studies across different disciplines.

  • 5 deciders

    drupal, deployment, automation, devops

    Decided on

    Configuration should never be in an overridden state after configuration import(s) have been completed.

  • 1 decider

    dev-tools, drupal, devops

    Decided on

    The software development industry is continuing to move to containers both for production and local environments. It's clear that the bulk of new investment in local tooling is going towards container-focused solutions. While containers themselves add some complexity to local environments, they also reduce variance in development environments for teams with multiple developers.

  • 4 deciders

    php, drupal

    Decided on

    PHP's type coercion can cause logical errors within a program. For example, when a float is cast to an int, the decimal portion is lost. We aim to reduce these errors in our code, but they can easily slip through manual code review. Following stricter typing where available can significantly reduce bugs, as shown by Python's urllib3 type hinting case study.

  • 4 deciders

    devops, locals, drupal, contrib-modules

    Decided on

    Lullabot often works on projects that have large numbers of static file assets in production, such as images or PDFs. Keeping a complete copy of those files for each environment is wasteful, since developers tend to only look at a small portion of a site locally. A solution is needed to reduce disk use and the time it takes to update an environment.

  • 4 deciders

    dev-tools, drupal

    Decided on

    When developing a Drupal website, additional modules and configuration are useful for local and development environments.

  • 1 decider

    scripting

    Decided on

    When writing scripts for CI tasks or local procedures, it is helpful to have the full command spelled out. Having the long options and avoiding command aliases will reduce chances of misinterpretation and mistakes. This will also reduce the need for checking the documentation while reading or reviewing a script.

  • 3 deciders

    drush, deployments

    Decided on

    When updating Drupal code and configuration in a given environment, it's useful to make sure all members of the team and all teams follow a consistent set of steps, in the same order. Having consistent steps across multiple projects will reduce onboarding for new team members.

  • 3 deciders

    contrib-modules, editorial-experience

    Decided on

    All Drupal websites our team works on have one or more environments. At a minimum, there will be a production and a local development environment. Most projects will have production, staging, development preview, and local environments. Developers and QA often access different environments at the same time. Since making content or configuration changes on the wrong environment can have unintended consequences, it is important to be able to distinguish environments easily.

  • 3 deciders

    dev-tools, doc, meta

    Decided on

  • meta

    Decided on

    We need to record the architectural decisions made on this project.