Modernizing a WordPress Development Workflow

Context

I was hired as a software engineering consultant by a marketing agency that built and maintained business websites using WordPress.

The agency had recently closed several new projects, but its only WordPress specialist was becoming overloaded. I was brought in to provide additional engineering capacity and support the specialist with the development work.

The existing process for building each website was largely manual. There was no shared development environment, source-control workflow, or automated deployment process.

My responsibility initially appeared to be straightforward: set up my own local environment and follow the existing workflow used by the WordPress specialist.

After reviewing that workflow, I identified an opportunity to address the underlying development process rather than simply reproducing it on another machine.

Problem

The agency had no formal development environment or reproducible setup process.

The WordPress specialist performed development directly on their laptop, maintaining multiple local LAMP environments for different projects. Each website was effectively developed and configured independently.

When a site was completed, the specialist manually uploaded it to the hosting provider and performed the required configuration there. The process was then repeated for the next client.

There was no Git repository for the projects and no automated mechanism for creating a consistent development environment or deploying changes.

This created several problems:

• development environments depended on an individual developer’s machine
• setting up a new project required significant manual work
• project configuration was difficult to reproduce
• there was no version-controlled source for the websites
• deployments depended on manual steps
• the existing workflow was heavily dependent on the single WordPress specialist

Rather than reproducing this workflow on my own machine, I raised the issue with the agency owner.

I proposed introducing a standard development and operations workflow that would reduce the amount of time spent on setup and deployment while also making the process usable by additional developers in the future.

Intervention

I approached the change as an incremental improvement to the agency’s existing workflow rather than attempting to replace its WordPress development practices.

Establishing a shared development workflow

After discussing the problem with the agency owner, I received approval to establish a GitLab organisation/account and begin documenting the new development and operational workflow.

The goal was to create a repeatable process that could be followed by the existing specialist and eventually by other developers joining the agency.

The first repository I created focused on the development environment itself.

I initially built a Vagrant-based environment together with Ansible playbooks that provisioned the required LAMP tooling. This allowed a new developer to create a consistent local environment without manually reproducing the specialist’s machine configuration.

This initial implementation also gave us a place to document the required setup and make the environment reproducible.

As the workflow matured, I replaced the custom environment management with the open-source tooling from Roots, including Trellis and the associated WordPress development tools. This reduced the amount of infrastructure and configuration that the agency itself needed to maintain.

Roots Trellis on GitHub | Roots.io

Introducing the specialist to the new workflow

Once the development environment was established, I worked directly with the WordPress specialist through a series of pairing sessions.

Rather than simply handing over documentation, I introduced the workflow interactively and adapted it based on their existing development process.

The new approach made creating a new website substantially simpler: instead of manually constructing another local environment, the developer could provision the required environment using the established tooling.

This was particularly important because the goal was not to make the process technically sophisticated for its own sake. It needed to be easier for the person who was actually using it.

Migrating existing projects into source control

With the development workflow established, I began migrating existing client websites into individual Git repositories.

This gave each project a version-controlled source and created a common place for the agency to maintain websites after delivery.

The migration also reduced the dependency on the specialist’s local machine as the implicit source of truth for each project.

Instead of a collection of sites existing primarily as local installations and deployed copies, the agency now had a reproducible project structure that could be checked out and developed by another person.

Preparing for a broader development workflow

The new process also changed what was possible for the agency operationally.

New developers could be introduced to a documented and reproducible development environment rather than being required to recreate the specialist’s personal setup.

The agency could also consider hosting and deployment providers that were better suited to version-controlled WordPress workflows, rather than being constrained by the limitations of the original manual deployment process.

Outcome

The development environment setup went from a process taking hours of manual configuration to a small number of command-line operations.

The agency moved from an individual, machine-dependent workflow to a shared development process based on:

• version-controlled Git repositories
• reproducible development environments
• documented setup procedures
• automated environment provisioning
• dedicated repositories for client projects
• established tooling for WordPress development and deployment

The WordPress specialist was able to work with the new workflow through pairing and progressively migrate existing projects into it.

The change also removed an important operational bottleneck: the agency was no longer dependent on reproducing one developer’s personal machine configuration whenever another developer needed to work on a project.

The resulting workflow made it easier for the agency to take on additional projects and subsequently provided a foundation for bringing additional developers into the development process.

It also enabled the agency to work with hosting providers and deployment workflows better suited to maintaining WordPress sites through version-controlled development practices.

Additional Context

The main constraint was that the WordPress specialist already had an established way of working and needed to continue delivering client projects while the workflow changed.

I therefore deliberately avoided introducing a large platform or requiring a complete change in how websites were authored. The objective was to remove repetitive infrastructure and deployment work around the existing WordPress development process.

The first implementation used Vagrant and Ansible because they gave the agency a straightforward way to reproduce the existing development environment. As the workflow matured, I adopted established open-source tooling from the Roots ecosystem instead of maintaining a growing collection of custom provisioning scripts.

This reduced the agency’s maintenance burden and allowed the development workflow to benefit from tooling designed specifically around WordPress development.

The work also served as an operational handover: the process and knowledge that had previously lived primarily with one specialist were progressively turned into repositories, tooling, and documentation that could be shared with other developers.