Terminal
Terminal/Skill
Checks a WooCommerce plugin update for existing merchants: database migrations, saved payment tokens, removed hooks, rollback, and upgrade notices.
By Automattic
Works with
npx skills add automattic/claude-woocommerce-toolkit --skill woocommerce-upgrade-safetyYou 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).
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 declarationsreferences/security.md -- Database patterns, Options API, prepared statementsreferences/plugin-architecture.md -- Plugin lifecycle hooks, activation/deactivationScan the diff between the old and new version for these high-risk patterns:
| Pattern | Why It's Risky |
|---|---|
Changes to *-install.php, *-activator.php, *Install* classes | Database migration code changed |
New/modified dbDelta() calls or $wpdb->query("ALTER TABLE") | Schema migration |
Changes to WC_Payment_Token* classes or wc_payment_token meta | Payment token schema |
Removed add_action/add_filter calls | Hook removal |
Changes to process_payment(), process_refund() | Core payment flow |
New/changed delete_option() calls | Settings migration |
Changed Requires at least, WC requires at least, Requires PHP headers | Minimum version bump |
If any of these patterns appear, run this skill.
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
dbDelta() or equivalent safe migration patternDROP TABLE or DROP COLUMN without a preceding version that stopped
writing to that table/column (two-release deprecation pattern)admin_init or plugins_loaded with a version check gate,
NOT on every page loadwp_options and checked before running migrationsSeverity:
| Issue | Level |
|---|---|
| Data loss (DROP without migration) | Critical |
| Non-idempotent migration | High |
| Missing version gate (runs on every load) | High |
| No schema version tracking | Medium |
LIMIT + offset, or Action Scheduler)wp_postmeta and
wc_orders_meta tables (use $order->get_meta() / $order->update_meta_data(),
never raw SQL against a specific table)get_option() fallback (avoids race conditions where code reads before
migration runs)This section applies only to payment gateway plugins. Skip for non-payment plugins.
WC_Payment_Token_CC, custom token types)
remain valid and usable after upgradeSeverity: Any token loss or breakage is Critical -- merchants' customers lose saved payment methods, increasing checkout friction and abandoned carts.
scheduled_subscription_payment_{gateway_id}) are still
registered with the same callback signaturepending or on-hold status with this payment method can still be
completed after upgrade_deprecated_hook() or _deprecated_function() called for any removed or
renamed hooks/functionsFeaturesUtil::declare_compatibility() calls are accurate (the plugin
actually works with the feature, not just declaring it)get_option() calls (v1 ignores
unknown settings)WC_Admin_Notices or WordPress admin notices (not just changelog text)readme.txt includes an == Upgrade Notice == section for this versionVersion: matches the release tagWC tested up to is updated to the latest WooCommerce releaseRequires at least is updated if minimum requirements changedRequires PHP is updated if minimum PHP version changedupgrade-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
[...]