Lessons Learned Maintaining Large Drupal Applications
Large applications rarely fail because one class is ugly. They become difficult when ownership, deployment, configuration, integrations, and observability drift apart.
Make ownership visible
Every integration and custom module needs a purpose, owner, dependency story, and retirement path. An inventory turns “legacy” from a complaint into a set of decisions.
Keep upgrades routine
Small, frequent dependency updates are easier to review than emergency leaps. Track deprecations early, test critical workflows, and keep contributed-module choices conservative.
Invest in operational knowledge
Runbooks, dashboards, structured logs, deployment notes, and incident reviews preserve knowledge beyond individual developers. Technical debt includes undocumented operations, not only code.
Protect the boundaries between code, configuration, and content
Long-lived Drupal sites become much harder to reason about when the same responsibility is represented in several places. Field definitions created by deployment scripts, configuration changed manually on production, and editorial values embedded in Twig can all work initially, but together they create multiple sources of truth.
Code should define application behavior, exported configuration should define deployable site structure, and content should remain in the database under normal editorial workflows. Exceptions exist, but they should be intentional and documented.
Budget for continuous upgrades
Waiting years between dependency reviews turns routine maintenance into a project. Regular core and contributed-module updates surface deprecations while the surrounding code is still familiar and keep security releases closer to the versions already under test.
The same applies to PHP, Composer, CI actions, and hosting assumptions. A Drupal application is an ecosystem, and every neglected layer can become the reason the next application update is difficult.
Treat integrations as owned products
An API integration needs more than credentials and a successful request. Document who owns it, what happens when it is unavailable, how authentication rotates, what data is authoritative, how failures are retried, and how the team knows it is unhealthy.
That operational ownership often matters more over ten years than the original amount of code required to build the integration.
Key Takeaways
- Inventory custom code and integrations.
- Make upgrades ordinary work.
- Treat operational documentation as part of the application.