WordPress Maintenance

Running a WordPress major upgrade step by step with WP-CLI — commands and checkpoints for each stage

The W series has covered what to check before a major upgrade, when to apply it, and what can go wrong. This fourth part covers the remaining question: how to actually run it. Once the preparation is in place and the timing is right, this is the command sequence to follow — one stage at a time, with a confirmation step at each boundary. Why not use the admin dashboard Update button The WordPress admin screen has an “Update All” button that runs core, plugin, and theme updates in a single operation. This is the approach to avoid for major upgrades. The reason is loss of isolation. When core plus …

Read more
Engineering Notes

Three site-list UX improvements: instant completion feedback, error highlighting, and auto-deselect

Three site-list UX improvements: instant completion feedback, error highlighting, and auto-deselect The site-list visualization work has run across several posts: the blue pulse and green completion border, the marker-based running-site detection, and the three-state visual hierarchy. v1.6.8 added three more UX improvements to the same area. This post records the design decisions behind them. All three share a common starting point: managing 10–20 sites in a bulk maintenance run that takes several tens of minutes, and making that time easier to follow without introducing new failure modes. Improvement 1 — refresh the thumbnail and badge the moment a site finishes Previously, thumbnails and the pending-plugin badge were only refreshed after …

Read more
Engineering Notes

Why environment variables don’t suppress WP-CLI PHP Deprecated warnings — the phar + shebang path and a three-part structural fix

A previous post covered how to absorb PHP 8.2 Deprecated warnings from WP-CLI using a three-layer defense. The approach — prepending WP_CLI_PHP_ARGS to set error_reporting — works in many environments. But a case came up where Deprecated warnings wouldn’t disappear despite the same configuration. Tracing the cause revealed a structural reason why the environment variable never arrived. This post records that root cause and the three-part fix added in v1.6.8. Why environment variables don’t arrive — the phar + shebang execution path An agency reported that on Xserver, plugin list retrieval was failing across multiple sites (referred to here as “site A / site B”) with a large volume of …

Read more
WordPress Maintenance

When SSH to Xserver suddenly stops working, it’s fail2ban — the official confirmation and a safer reconnection check

If you run WordPress maintenance for clients on Xserver, sooner or later you hit this: SSH was working fine this morning, and now your connection dies the instant it touches the host. No key change on your side, no obvious server-side incident. Just Connection closed by …, and the silence deepens every time you retry. A recent escalation to Xserver support gave us an official answer about what’s actually going on. Worth writing down what an operator needs to know. What the symptom looks like In our observation, the symptom moves through two stages. Lighter: Connection closed by [Xserver IP] — connection killed at the sshd layer before it’s established …

Read more
WordPress Maintenance

Five failure patterns from past WordPress major upgrades — what 5.0 Gutenberg through 6.0 FSE taught maintenance teams

With the pre-upgrade checklist of seven items and the calibration framework for when to apply, we’ve covered preparation and timing for WordPress major upgrades. The third installment is “what can go wrong” — the failures that actually happened in past majors, organized into five patterns. The examples are tied to specific releases (5.0 / 5.6 / 6.0), but the point is that the same structural patterns repeat in new majors. Carrying these as types in your head pays off when 7.0 or 8.0 lands and you need to triage fast. Pattern 1 — “Editor-adjacent UI extensions” disappear en masse (5.0 Gutenberg) The most operationally impactful incident when WordPress 5.0 standardized …

Read more
WordPress Maintenance

Don’t apply WordPress major releases on day one — the x.0.1 rule and a calibration framework

The companion to the seven things to check before a WordPress major upgrade is the question that comes right after: when do you actually apply it? A new WordPress major drops today. Do you ship it to production tonight? Tomorrow? In a week? Hold for the next scheduled monthly maintenance? This call tends to live in tribal knowledge, but a few clear axes combined together give you a calibration framework you can apply every time without re-deciding from scratch. Here are five axes worth using. Premise — majors are not security patches The first thing to anchor: a major upgrade is not a security patch. WordPress ships security fixes via …

Read more
WordPress Maintenance

Seven things to check before a WordPress major upgrade — before patch what breaks after becomes a disaster

WordPress major version upgrades (5.x → 6.x, and eventually 6.x → 7.x) are a different animal from minor releases. Minor releases (like 6.4.1 → 6.4.2) are mostly bug fixes with low compatibility risk. Majors land API deprecations, raised PHP minimum requirements, and core block replacements all at once — and those things hit operations hard. The “just hit Update in the admin and patch whatever breaks” workflow can survive on a single personal site, but it tends to fall apart under multi-site maintenance — simultaneous failures across sites overwhelm root-cause triage. This post collects the things worth verifying before you run a major upgrade, as a seven-item checklist. 1. Has …

Read more
Engineering Notes

A variable I refactored into one function — and kept referencing from another. Python lazy evaluation hid it, and an AST test finally caught it

One day the browser automation flow started failing right after plugin updates with NameError: name ‘plugin_form_selectors’ is not defined in the post-update “residual check” step. The refactor that introduced this had landed back in v1.6.1. The error didn’t surface until many rounds later. Reading the code, the cause is obvious in seconds — but nobody hit it for ages, because Python’s lazy evaluation kept the leftover reference hidden until exactly the right execution path ran. This post walks through what the bug was and how we structurally prevented its kind via an AST static-analysis test. What happened — a reference that crossed a scope boundary browser_utils.py has two functions involved: …

Read more
WordPress Maintenance

When the same selector appears twice on a WordPress admin page — Playwright strict mode and the .first habit

For sites where SSH isn’t available, we drive maintenance through Playwright by automating the WordPress admin UI. Plugin updates, theme updates, translation updates — all running fine. Until one day, only the Core (WordPress itself) update started failing. The error was Locator.click: strict mode violation — familiar to anyone who’s used Playwright, the one that fires when a locator matches multiple elements. Tracing it back, the root cause turned out to be a structural quirk of the WordPress admin UI sitting right at the trap line. This post walks through the bug from the angle of Playwright’s strict mode and making .first a habit. Strict mode violation is “your selector …

Read more
Engineering Notes

The day a user told me the running site looks weak — rebuilding the three-state visual hierarchy with background color

After we’d shipped the colored borders for in-maintenance and completed sites on the multi-site list, real-world usage produced an unexpected report: “the running site somehow looks weak.” Followed by: “the green border that’s supposed to stick for 24 hours doesn’t show up.” The first one was surprising. The running site has a pulsing blue border — it should be obvious. But when I looked at the screen again, yes, it did look weak relative to its neighbors. The problem turned out not to be the running-state color itself, but a hierarchy among the three states that had quietly inverted. This post walks through that visual-hierarchy collapse and rebuild, along with …

Read more