All ADRs
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.
Use JavaScript strict mode
accepted
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.
Use CSS Logical Properties
accepted
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.
Use local copies of patch files
accepted
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.
Consistently name entity fields
accepted
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.
Use DDEV for local environments
accepted
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.
Use strict types in PHP code
accepted
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.
Environment Indicator
accepted
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.
Use Log4brains to manage the ADRs
deprecated
3 deciders
dev-tools, doc, meta
Decided on
Record architecture decisions
accepted
meta
Decided on
We need to record the architectural decisions made on this project.