All ADRs

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

Loading JavaScript as deferred has the best default performance

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.

Loading JavaScript as async & deferred has the best default performance

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

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

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

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

Opt in to settings that raise errors for problematic code.

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

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

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

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

We need a site generator to publish our ADRs.

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

Inclusive language can make technical subjects more inviting and understandable.

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

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

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

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

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

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.

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

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

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

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

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

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.

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

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

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.

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.

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.

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

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.

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.

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.

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