Review a WordPress multisite plugin upgrade before delegating it

One codebase does not make the sites equivalent

A multisite network can contain locally activated and network-activated plugins, custom roles, mapped domains, old theme integrations, and very different data volumes. Build cohorts from those differences. For each cohort, record site identifier, activation scope, active theme, relevant options, custom roles, scheduled hooks, content scale, and integration owner. Testing one convenient site and calling it “multisite coverage” hides the exact variation likely to break.

Clone representative sites into staging with minimized data and disabled outbound effects. Explain why each selected site represents a cohort and list the exceptions receiving their own check. Capture schema, plugin version, role map, and scheduled events before upgrade. A reviewer needs a before state that can be compared, not a memory of how the dashboard looked.

Activation history changes what upgrade code does

Reproduce local activation before network activation, a site skipped by an older migration, deactivation with tables retained, and later reactivation. Install the candidate through the path the network will use. Observe option versions, table changes, activation callbacks, and repeated upgrade requests. Run activation twice where safe to show schema work is idempotent.

Visit network administration and individual site dashboards, then run deferred jobs. A success notice in the network screen does not prove that every site-level migration ran. Watch for a migration that executes on every request or a network hook that creates duplicate rows per site. Store site identifiers with evidence so failures cannot be attributed to the wrong cohort.

Custom roles and background work deserve their own tests

Create disposable users shaped like network administrator, site administrator, editor, contributor, and one real custom role. Exercise important admin screens, REST actions, and public effects. Check allowed work and denials. A menu hidden from a user does not prove the endpoint is protected, while a broad capability added during upgrade may expose records far beyond the intended screen.

Capture scheduled events immediately after upgrade and after due work runs. Interrupt one background job and resume it. Verify that mail goes to a sink and payment or marketing integrations use sandboxes. A staging clone with live destinations can send customer messages even though the plugin change itself is correct. Side-effect isolation belongs in the report, not only in environment notes.

Old code may not understand new stored data

Restore the previous plugin code on a staging cohort after the migration and document what still works. If old code cannot read the new schema or option format, a code rollback is not a recovery plan. State which database backup would be required and which unrelated site changes that restore would erase. Depending on the migration, forward repair may be safer than a network-wide restore.

Use a cohort rollout with a pause and evidence check between groups. Hand off database diffs, event snapshots, capability results, public and admin flows, error logs, backup references, stop conditions, and the person who approves continuation. Production network activation and restoration remain operator actions. The developer’s contribution is a repeatable upgrade and clear evidence, not unilateral authority over every site.

Upgrade representative sites instead of treating the network as one site

Select a small cohort from synthetic or sanitized staging sites that represents network-activated use, site-only activation, inactive installation, custom tables, alternate themes, different languages, and the largest supported content shape. Record the current plugin version, schema marker, activation state, and relevant scheduled events for each. Upgrade one cohort at a time and visit both network administration and the public routes the plugin changes. A successful network dashboard does not prove a site-specific table migrated or that an inactive site will initialize correctly when activated later. Create a new site after the upgrade and activate the plugin there; its clean-install schema should match an upgraded site's schema. Deactivate and reactivate one upgraded site without rerunning destructive conversion. If the plugin registers cron events, count them before and after so repeated activation does not create duplicate jobs. Check roles from both network and site contexts because super-admin success can hide a missing capability for ordinary administrators.

Build a failure fixture around the plugin's actual storage boundary. Interrupt a batched table conversion, resume it, and compare rows, indexes, and the recorded schema version. Introduce one malformed option or content record and ensure it is reported without blocking every other site. Measure query time and locks on a representative large site while normal reads continue. If rollback restores old code, document whether the new schema remains readable; database rollback is a separate and potentially destructive operation. Test uninstall only in a disposable site and verify the agreed retention policy rather than assuming all plugin data should disappear. The delivery package should list cohort identifiers, activation modes, before-and-after schema fingerprints, cron counts, capability checks, malformed-record results, performance observations, and rollback limits. Network owners decide rollout order, maintenance windows, and data retention. Keeping those choices outside the upgrade routine allows the developer to concentrate on idempotent code and evidence without gaining broad authority over every tenant in the network.

Review cache and request isolation across the cohort. Purge only the fixture site's cache after its migration and verify another site's option values and public output do not change. Exercise domain-mapped and subdirectory URLs if the network supports them, and check REST, command-line, and scheduled entry points in addition to browser pages. Run the upgrade command twice to demonstrate idempotence, then run it as a principal that lacks network authority and expect a clean refusal. Compare database queries and error logs before and after activation on a fresh site. Keep screenshots secondary to table fingerprints, request results, and event counts. Those artifacts show whether the plugin respects tenant boundaries and can be resumed, which are the two properties a large multisite rollout needs before any administrator expands the cohort.

Buyer questions

Questions about planning the role