Enterprise Drupal website development in Quincy

A modern Drupal site is assembled by Composer, the PHP dependency manager. Core, contributed modules, themes and their PHP libraries are all packages listed in one file, composer.json, with the exact installed versions pinned in a second file, composer.lock. Understanding those two files explains most of what goes wrong during updates. Start with the difference between them.

The json file states intentions. It says the site wants Drupal core in a given major version and a contributed module within a compatible range. The lock file records reality: the precise version of every package, including the dozens of libraries nobody asked for directly. Both files belong in version control. Committing only the first one means every environment may resolve slightly different versions, and bugs appear that nobody can reproduce.

The vendor directory and the downloaded modules usually do not belong in version control. They are rebuilt from the lock file with a single install command. That keeps the repository small and makes the build repeatable. A deployment pipeline runs the install, then applies database updates and imports configuration.

Updates happen in two steps. First, update the lock file on a development copy, one module or one group at a time, and read what changed. Slowly. Then commit the new lock file and let the pipeline build it everywhere else. Running a blanket update on production pulls in whatever is newest at that moment, which is how a site ends up with an untested library at midnight.

Version constraints deserve care. A caret constraint allows minor and patch releases, which is usually right for contributed modules. Pinning an exact version makes sense only for a temporary reason, such as waiting for a fix, and the reason should be written in a comment or a ticket. Forgotten pins are why some sites still run a module several releases behind with no one knowing why.

Patches are a normal part of Drupal work. A bug in a contributed module often has a fix sitting in the issue queue for weeks before release. The composer-patches plugin applies such fixes during every build, listed by URL or stored as local files. Store them locally. Remote patch files can change or vanish, and a build that depended on one will fail without warning.

Custom modules and the custom theme live in their own directories in the repository and do not come from Composer at all, unless they are shared across several sites. For a group of related sites, a private package repository lets each one require the shared code at a known version.

Security releases test the setup. They arrive without notice. A good pipeline turns a core security update into a small pull request: one updated lock file, a passing build, a deployment. A poor one turns it into an afternoon of guessing which files were edited by hand on the server.

Inherited sites need a quick check. Two warning signs matter most. A modules folder full of code with no matching entry in composer.json. And a lock file that has not changed in a year. Either one is a red flag. The build is not really under control yet.

When composer why and composer why-not return clear answers, the project is healthy. Those two commands explain which package required a library and what blocks an upgrade, and they save hours on every major update.

Drupal stores two kinds of things in its database. Content is what editors create: pages, articles, media, users. Configuration is how the site is built: content types, fields, views, image styles, roles, block placements, workflow states. The configuration management system in core exports the second kind to YAML files so it can be tracked, reviewed and deployed.

The flow is simple on paper. A developer changes something on a local copy, for example adds a field to the event content type. They export configuration, which writes changed YAML files to a sync directory. Those files are committed, reviewed and deployed. On the target environment, an import applies the changes to its database. Production never needs anyone clicking through the field interface.

The trouble starts when production changes on its own. A site builder adds a block on the live site or tweaks a view to fix something urgent. The next deployment imports configuration from code and quietly reverts that fix, because the code does not know about it. Two rules prevent this. Lock configuration editing on production where possible, and check for differences between the live site and the sync directory before every import.

Some configuration should differ per environment. Error logging verbosity, the mail system, API keys for a payment provider, a module that is only useful during development. Config Split, a contributed module, handles this by defining sets of configuration that are active only on certain environments. Secrets, though, should not live in YAML at all. Keep them in environment variables or the settings file and reference them from there.

Editors sometimes own a piece of configuration. The text of a site-wide notice, menu items, or the contact address in a form. If those are exported, every deployment will overwrite what editors set. Config Ignore excludes chosen items from import so editorial changes survive. Deciding which items belong to editors is a conversation worth having early, with a written list at the end.

Reviewing configuration diffs takes practice. YAML for a single view can run to hundreds of lines, and a small change moves many of them. Reviewers learn to look for the meaningful keys: permissions granted to a role, fields made required, filters changed on a public listing. Permission changes deserve the closest look, because a single line can open an administrative page to anonymous visitors.

Configuration import order matters on larger changes. Deleting a field that still holds data, or renaming a content type, needs an update hook alongside the export so existing content is migrated before the structure changes. The export records the end state. It does not know how to move the data.

A new developer should be able to install the site from configuration alone and get a working, empty copy. If that fails, some part of the site lives only in the database, and that part is at risk.

One practical habit helps new staff. Keep a short page in the repository that explains the export and import commands, the split sets, and the ignored items. Update it whenever the setup changes. Nobody should have to learn it from a failed deployment.

Treat the sync directory as the true description of the site. When the files and the live database disagree, someone should find out why that same day.

Every Drupal project starts somewhere. For years the answer was the same. It meant a blank core install followed by weeks of assembling the same modules: a WYSIWYG setup, media handling, SEO metadata, redirects, a sitemap, an admin theme, sensible roles. Recipes, added to core in recent versions, change that starting point. The Drupal CMS product goes further. It packages many of them into a ready install.

A recipe is a folder with a small YAML file and optional configuration. Applying it installs a set of modules and applies configuration in one step. A recipe might set up a blog with tags and a listing page, add an events type with a date field and a calendar view, or configure privacy-friendly analytics. Unlike an old installation profile, a recipe is applied once and then gets out of the way. The site stays free.

That last point matters. It matters more than it sounds. Distributions used to be the way to start from something bigger than core. They bundled modules, configuration and a profile, and a site built on one depended on the distribution maintainers for its updates. Then a distribution slowed down. Sites built on it were stranded. Recipes avoid that trap because the result is plain configuration owned by the site.

Drupal CMS is the practical face of this approach. It gives editors a friendlier admin experience, a set of preinstalled recipes, and a project browser for adding more. For a marketing site or a small organisation, it can remove much of the early setup. For a complex platform, it is still a starting point that the team will reshape, and it helps to know which recipes were applied so their configuration can be read and adjusted.

Teams that build many Drupal sites can write their own recipes. A house recipe might install the standard security modules, configure the editor toolbar the way the content team likes it, set up roles and a moderation workflow, and add the monitoring integration. New projects start from that shared baseline in minutes. When the baseline improves, the recipe is updated for future projects, and existing sites are brought in line deliberately, through normal changes.

There are limits. A recipe does not update itself on sites where it was already applied. Configuration it created may later be edited by hand, and applying a newer version may conflict with those edits. Recipes also assume certain modules are available through Composer, so the project still has to require them. It also has to keep them updated.

Starter kits for themes follow the same idea. Core ships a starter kit that generates a new theme as a copy, instead of making it a subtheme of a base theme that may change underneath. The generated theme belongs entirely to the project. Nothing upstream can break it.

Choosing where to begin is a real decision, so make it explicitly. A blank core install gives the most control and the most setup. Drupal CMS gives speed and opinions. A house recipe gives a known baseline for teams that build often. Each has a price.

Whatever the choice, record it in the project README. The next developer should know that the site began from a recipe, which one, and what was changed afterwards.

That single paragraph saves a day of archaeology later.