woocommerce-upgrade-safety

WooCommerce Plugin Upgrade Safety Review

You are performing an upgrade safety review for a WooCommerce plugin that is about to ship a new version to existing merchants. This skill is concerned exclusively with what happens to existing installations during and after the upgrade -- not with the quality of the new code itself (that is covered by code review skills).

Foundation References

Read these before starting -- they define the patterns you are auditing against:

• references/woocommerce-apis.md -- HPOS, CRUD, data stores, Payment Token API, feature compatibility declarations
• references/security.md -- Database patterns, Options API, prepared statements
• references/plugin-architecture.md -- Plugin lifecycle hooks, activation/deactivation

When to Use

• Before any minor version (1.x -> 1.y) or major version (1.x -> 2.0) release
• When a release includes database schema changes, settings restructuring, new feature declarations (HPOS, blocks), or deprecated hooks/filters
• When a release changes the payment flow (new tokenization method, new API version, hosted fields migration)
• Skip for patch releases (1.0.x -> 1.0.y) that contain only bug fixes with no structural changes

How to Detect When This Skill Is Needed

Scan the diff between the old and new version for these high-risk patterns:

If any of these patterns appear, run this skill.

Step 0: Establish Upgrade Context

1. Identify the current released version (what merchants have today)
2. Identify the target version (what is about to ship)
3. Produce a diff summary:
   • Files added, modified, deleted
   • Database schema changes (new tables, altered columns, new meta keys)
   • Settings fields added, removed, or renamed
   • Hooks/filters added, removed, or signature-changed
   • Payment Token schema changes
   • Minimum version requirements changed (PHP, WP, WC)

If both versions are in git:

git diff v<old>..v<new> --stat
git diff v<old>..v<new> -- src/Data/ includes/class-*-install.php

Step 1: Database Migration Safety

1.1 Schema Migrations

• All schema changes use dbDelta() or equivalent safe migration pattern
• Migrations are idempotent -- running the upgrade routine twice produces the same result (merchants may trigger activation multiple times)
• Column type changes are backwards-compatible (e.g., widening a VARCHAR, not narrowing it)
• New required columns have sensible defaults so existing rows are valid
• No DROP TABLE or DROP COLUMN without a preceding version that stopped writing to that table/column (two-release deprecation pattern)
• Migration runs on admin_init or plugins_loaded with a version check gate, NOT on every page load
• Schema version is stored in wp_options and checked before running migrations

Severity:

1.2 Data Migrations

• Existing order meta is preserved or migrated to new keys (not silently orphaned)
• If meta keys are renamed: old keys are read as fallback during a transition period, not immediately deleted
• If data format changes (e.g., serialized -> JSON, or flat -> structured): migration converts existing records, does not assume new format
• Migration handles large datasets without hitting PHP memory/timeout limits (batch processing with LIMIT + offset, or Action Scheduler)
• HPOS compatibility: if migrating order meta, works with both wp_postmeta and wc_orders_meta tables (use $order->get_meta() / $order->update_meta_data(), never raw SQL against a specific table)

1.3 Options / Settings Migrations

• If settings keys are renamed or restructured: old settings are read and migrated on upgrade, not lost
• If settings are moved between storage backends (options -> custom table, or vice versa): migration runs before any code reads from the new location
• Autoloaded option size is checked -- migrations should not create large autoloaded options (>100KB triggers performance degradation)
• Default values for new settings are set during migration, not left to get_option() fallback (avoids race conditions where code reads before migration runs)

Step 2: Payment Continuity

This section applies only to payment gateway plugins. Skip for non-payment plugins.

2.1 Saved Payment Tokens

• Existing saved payment tokens (WC_Payment_Token_CC, custom token types) remain valid and usable after upgrade
• If the token storage schema changes: migration converts existing tokens
• If switching from custom token storage to the WC Payment Token API (or vice versa): migration preserves all existing tokens
• If switching payment processor API versions: existing tokens are compatible or migrated (e.g., Stripe Sources -> PaymentMethods migration)
• Merchants' customers can check out using saved cards immediately after upgrade without re-entering payment details

Severity: Any token loss or breakage is Critical -- merchants' customers lose saved payment methods, increasing checkout friction and abandoned carts.

2.2 Active Subscriptions

• If the plugin supports WooCommerce Subscriptions: active subscription renewal payments will continue to process correctly after upgrade
• If the API integration changes: existing subscription payment profiles / mandates are compatible with the new flow
• Renewal hooks (scheduled_subscription_payment_{gateway_id}) are still registered with the same callback signature

2.3 Pending Transactions

• Orders in pending or on-hold status with this payment method can still be completed after upgrade
• Webhook/IPN handlers still accept callbacks for transactions initiated before the upgrade (old API format, old webhook signature scheme)
• If the webhook endpoint URL changes: old URL still routes to a handler (or returns a meaningful error, not a 404)

Step 3: Hook and Filter Compatibility

3.1 Removed or Renamed Hooks

• List all hooks/filters present in the current version but absent in the target
• For each removed hook: is there a replacement? Is the old hook deprecated with a notice before removal? (Should follow two-release deprecation: deprecate in release N, remove in release N+2)
• _deprecated_hook() or _deprecated_function() called for any removed or renamed hooks/functions
• Third-party plugins or themes hooking into removed hooks will not fatal error

3.2 Changed Signatures

• List all hooks/filters where the number or type of parameters changed
• Changed signatures documented in the changelog
• If a filter return type changed: existing filter callbacks returning the old type will not cause a fatal error or data corruption

3.3 New Feature Declarations

• If the plugin newly declares HPOS compatibility: verified that the upgrade path from non-HPOS-aware to HPOS-aware does not break existing order access
• If the plugin newly declares block checkout compatibility: existing classic checkout integrations still work (do not remove classic support when adding blocks support)
• New FeaturesUtil::declare_compatibility() calls are accurate (the plugin actually works with the feature, not just declaring it)

Step 4: Rollback Safety

4.1 Downgrade Resilience

• If a merchant downgrades to the previous version after upgrading: the plugin does not fatal error
• Database schema changes are forward-compatible: columns added by v2 do not break v1's queries (v1 ignores unknown columns)
• Settings added by v2 do not break v1's get_option() calls (v1 ignores unknown settings)
• If the migration is destructive (cannot be reversed): this is documented in the changelog and release notes with a "backup before upgrading" warning

4.2 WordPress Auto-Update Safety

• The plugin does not break WordPress auto-update compatibility
• If the upgrade requires manual steps (e.g., re-entering API credentials): an admin notice clearly communicates this after auto-update
• Post-upgrade tasks that require admin attention are surfaced via WC_Admin_Notices or WordPress admin notices (not just changelog text)

Step 5: Changelog and Merchant Communication

5.1 Changelog Quality

• Changelog entry exists for this release
• Format follows "Keep a Changelog" or WordPress conventions
• Breaking changes are called out explicitly (not buried in a list)
• Migration steps (if any) are documented with clear instructions
• Deprecated features are listed with their replacement

5.2 Upgrade Notice

• readme.txt includes an == Upgrade Notice == section for this version
• If the upgrade requires action: the notice says so clearly
• If the upgrade has breaking changes: severity is communicated ("backup your site before upgrading")

5.3 Version Metadata

• Plugin header Version: matches the release tag
• WC tested up to is updated to the latest WooCommerce release
• Requires at least is updated if minimum requirements changed
• Requires PHP is updated if minimum PHP version changed
• If minimum requirements increased: changelog documents this and the upgrade notice warns merchants on older versions

Step 6: Synthesize Upgrade Safety Report

Deliverable: upgrade-safety-report.md

# Upgrade Safety Report
## Plugin: [name] v[current] -> v[target]
## Date: [date]

### Upgrade Risk Level: [LOW / MEDIUM / HIGH / CRITICAL]

| Risk Level | Definition |
|------------|------------|
| LOW | No schema changes, no breaking changes, patch-level fixes |
| MEDIUM | New settings or meta keys, new feature declarations, minor hook changes |
| HIGH | Database schema changes, payment flow changes, deprecated hooks |
| CRITICAL | Data migration required, payment token schema change, minimum version bump |

Note: Major version bumps (X.0.0) start at HIGH minimum regardless of content.

### Database Migrations
| Migration | Idempotent | Batched | Reversible | Status |
|-----------|-----------|---------|------------|--------|
| [description] | Yes/No | Yes/No | Yes/No | PASS/FAIL |

### Payment Continuity
| Check | Status | Notes |
|-------|--------|-------|
| Saved tokens preserved | PASS/FAIL/N/A | [details] |
| Active subscriptions safe | PASS/FAIL/N/A | [details] |
| Pending transactions safe | PASS/FAIL/N/A | [details] |
| Webhook backward compat | PASS/FAIL/N/A | [details] |

### Hook Compatibility
| Hook/Filter | Change | Deprecated? | Replacement | Status |
|-------------|--------|-------------|-------------|--------|
| [hook name] | Removed/Renamed/Signature | Yes/No | [replacement] | PASS/FAIL |

### Rollback Assessment
- Downgrade safe: [Yes / No / Partial]
- Auto-update safe: [Yes / No -- requires manual steps]
- Manual steps required: [list, or "None"]

### Changelog Review
- Breaking changes documented: [Yes / No / N/A]
- Upgrade notice present: [Yes / No]
- Version metadata current: [Yes / No]

### Prioritized Upgrade Issues

## Critical
### UPG-001: [Brief description]
- **Category:** [Database / Payment / Hooks / Rollback / Changelog]
- **File:** [path]
- **Lines:** [N-M]
- **Issue:** [What is wrong]
- **Merchant Impact:** [What breaks for existing merchants]
- **Fix:** [What to change, with before/after code]
- **Status:** [ ] Not started

## High
[...]

## Medium
[...]

Step 7: Save and Present

1. Save the report
2. Present a one-paragraph risk summary
3. If Critical or High issues exist: recommend blocking the release until resolved
4. If the upgrade risk level is HIGH or CRITICAL: recommend the partner include a "backup before upgrading" notice in the release

Important Notes

• This skill does NOT evaluate code quality, security, or UX -- those are handled by other review skills
• Focus exclusively on the delta between versions, not absolute quality
• Payment token preservation is the highest-stakes item -- verify thoroughly
• Database migrations that work on 10 test orders may fail on 10,000 production orders due to memory/timeout -- always check for batching
• WordPress auto-updates mean merchants may upgrade without reading the changelog -- surface breaking changes via admin notices, not just documentation