Legacy WordPress web development workflow

Before you accept a project involving an existing WordPress website, ask yourself some important questions:

• Do we want to work with WordPress at all? (still? again?)
• Are we still ready to do it? What will we probably need to learn?
• Which legacy decisions and technical debt will we have to deal with?
• Do we know if it is possible to achieve our goals using the given technology (e.g. a certain theme or page builder)?
• Do our clients even know what they want or need?
• Do we suspect they have additional implicit requirements?
• Do they have enough budget to pay for our work?
• Are we still willing to accept the assignment?

As you are still reading this article, I suspect that – despite having answered “no” or “I don’t know” at least 1x – you are desperate enough or have other reasons like networking/marketing or hoping for a follow-up project and you have agreed to work with a legacy WordPress website that already starts to cause trouble.

We can reduce risks and troubles by using common sense and extra careful measures. Most importantly, always back up all data before making any changes!

What I do when I have to work with page builders to modify existing legacy websites:

• Investigate the existing setup by
  • taking screenshots
  • running automated audits like
  • and saving the current state to web.archive.org
  • for the most important page types, e.g.
    • the home page
    • another static page
    • a blog archive (category page)
    • a single blog entry.

Next:

• Make a backup! UpdraftPlus is a good tool as its backups can be used for cloning WordPress websites, including purchased plugins, to development and staging systems.

• Download the backup files to my local computer!

• Setup a development instance! We can start with a 1-click-installation on shared hosting, or use a Docker-based template like wp_cli_docker for local development.

• Restore/migrate the original content to your local copy. UpdraftPlus will adjust all absolute URLs and ensure a working media library on the target instance.

• Reset the main admin user (either in wp-admin or using the mySQL cli inside the database Docker container) and change its email address.

• Delete all other users!

• Delete all personal and customer data!

• Change the site title and the bookmark icon. My local development setups titles usually start with “Local” and the icons can’t be confused with the production ones.

• Update WordPress and its plugins in my local development instance.

• Verify that everything still works!

Don’t update any part of a client production site before creating and downloading a full backup, and don’t do it before taking screenshots and saving archive examples! If anything breaks, we need to know the last working state!

Ask your client if they prefer an “under construction” notice while you are making changes to their production site.

• Examine the existing setup for custom code and styles, e.g.
  • Appearance -> Customize -> additional CSS
  • Widgets
  • any other place where themes or custom plugins allow to define custom code
  • custom PHP code in a child theme;

• copy the existing code to project files like custom.css, custom.js, example-child/functions.php and commit it.

• Disable performance, caching, and security plugins locally before proceeding with the actual web development. They don’t help while developing, but their optimization can get in our way, cause outdated page styles and waste memory and energy.

• If we want to show our customer a preview to test, we can setup a public staging instance, transfer a new backup from localhost (which is already free from customer data and optional plugins), and set up password protection to make sure only the right people have access to our stage!

• If we don’t do staging, we can add a draft page on their production server where we can show some progress and make sure that we are really able to copy our work from localhost to production selectively.

Next, I try to find out how best to work with the given setup, how to persist my changes, and how to safely transfer them to another page or instance without breaking or forgetting anything.

As a web developer with a frontend focus, I try to use global CSS as much as possible. I know this contradicts the intention of no-code page builders, but so does coding in general. I found this to be a pragmatic compromise between staying in control of my code and not completely throwing away existing code and software.

Global custom CSS is prominent and easy to find compared to element-specific custom CSS or plugin-specific configurations that might stop working after the next major update.

Depending on the website’s complexity and our experience with its technologies, we might have spent at least half an hour or the whole day getting a grip on a legacy setup without any visible achievement. Before we start coding, we should review our assignment and find an easy subtask to begin with, ideally something that causes a change that is obvious at first sight.

So we can finish our first hour or day of work with a feeling of achievement.

Further work

When proceeding with our work, we must stay careful.

Communication

• Inform our clients what we are about to do, especially when it involves risks our downtimes!
• Turn our phone on an watch our inbox, chat and project management tools for any important inbound messages!
• Check communication for possible misunderstandings, and rather ask a silly question than make a wrong assumption!

Safety

• Always make sure we know which instance/server we are working on!
• Never work with outdated data! Reload content before resuming work after a break!
• Save and commit changes frequently!
• Don’t stop creating and downloading backups!

Payment and recommendation

• Always make the client happy, or at least don’t leave them disappointed or angry!
• If a project fails, or your client thinks it does, discuss solutions and possible exit and handover scenarios. We could also offer clients a reasonable discount when writing our final invoice.
• Bailing out might prevent making things worse and save time and money sometimes, but it can be better to invest an extra effort and save a project without telling the client, and turn an economic loss into a marketing investment: a happy customer might recommend our services to others.

Takeaways

• Take notes! If you find out “dirty secrets” or clever workarounds, if you learn new concepts related to WordPress or (web) development in general, write it down in a digital medium and be verbose enough to be able to find the information next time you need it!

As you can see, I keep posting about WordPress. I keep taking on clients with legacy WordPress websites, and I don’t rewrite their code from scratch. I hope that my hints and rants turn out to be helpful for anyone. Publishing this kind of post is another way to preserve my knowledge and find it the next time I google an error message.