Deprecate legacy back_compat_conversions syntaxes#6356
Conversation
Runner::back_compat_conversions() silently rewrites a set of pre-1.0 command and flag syntaxes to their modern equivalents. Nothing ever warned about them, so a user on the old syntax has no signal that it is outdated. Emit a deprecation warning naming the modern form at each legacy conversion site, while keeping the rewrite working. These syntaxes are scheduled for removal in 4.0. The warning is written directly to STDERR (like the existing --blog deprecation in Configurator), because the conversion runs during the ConfigureRunner bootstrap step, before the logger is initialized. The genuinely-permanent shorthands are left untouched: --help, --version/--info, --json, and the Windows PowerShell numeric-ID splitting. Existing tests that used deprecated forms are updated: the `wp cli aliases` scenarios now also assert the deprecation notice, and the `wp core config` usages switch to `wp config create`.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughLegacy WP-CLI command and flag rewrites now emit standardized deprecation warnings to STDERR while preserving existing conversions. Feature coverage verifies warnings, retained output, supported shorthand behavior, and modern ChangesLegacy syntax deprecation
Estimated code review effort: 3 (Moderate) | ~20 minutes Suggested reviewers: Sequence Diagram(s)sequenceDiagram
participant CLI
participant Runner
participant STDERR
participant Command
CLI->>Runner: invoke legacy command or flag syntax
Runner->>STDERR: emit deprecation warning
Runner->>Command: dispatch rewritten modern syntax
Command-->>CLI: return existing command output
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@features/back-compat.feature`:
- Around line 8-46: Expand features/back-compat.feature with Behat scenarios
covering the newly warned conversions: *-meta, --admin_name, core language,
checksum aliases, --site_id, transient aliases, plugin scaffold, and URL
shortcuts. For each, assert the deprecation warning plus successful
rewritten-command output and exit behavior, and add warning-free coverage for
--help, --info, and --json while preserving the existing shorthand behavior
checks.
In `@features/config.feature`:
- Around line 212-214: Update the fixture key from “core config” to “config
create” so Runner::run_command() applies the extra-php configuration to the
renamed command. Add a separate legacy “wp core config” scenario that verifies
the deprecation warning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 0d49ee7a-8388-4aeb-928a-63f7852396b2
📒 Files selected for processing (5)
features/aliases.featurefeatures/back-compat.featurefeatures/config.featurefeatures/validation.featurephp/WP_CLI/Runner.php
| Scenario: A deprecated top-level command alias warns | ||
| Given an empty directory | ||
|
|
||
| When I try `wp sql` | ||
| Then STDERR should contain: | ||
| """ | ||
| The 'wp sql' syntax is deprecated and will be removed in WP-CLI 4.0. Use 'wp db' instead. | ||
| """ | ||
|
|
||
| Scenario: A deprecated subcommand syntax warns | ||
| Given an empty directory | ||
|
|
||
| When I try `wp plugin update-all` | ||
| Then STDERR should contain: | ||
| """ | ||
| The 'wp plugin update-all' syntax is deprecated and will be removed in WP-CLI 4.0. Use 'wp plugin update --all' instead. | ||
| """ | ||
|
|
||
| Scenario: A deprecated flag warns | ||
| Given an empty directory | ||
|
|
||
| When I try `wp post list --ids` | ||
| Then STDERR should contain: | ||
| """ | ||
| The '--ids' syntax is deprecated and will be removed in WP-CLI 4.0. Use '--format=ids' instead. | ||
| """ | ||
|
|
||
| Scenario: Retained shorthands are not treated as deprecated | ||
| Given an empty directory | ||
|
|
||
| When I run `wp --version` | ||
| Then STDOUT should contain: | ||
| """ | ||
| WP-CLI | ||
| """ | ||
| And STDERR should not contain: | ||
| """ | ||
| is deprecated | ||
| """ |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
Expand acceptance coverage for the deprecation contract.
These scenarios do not cover newly warned conversions such as *-meta, --admin_name, core language, checksum aliases, --site_id, transient aliases, plugin scaffold, and URL shortcuts. The existing warning cases also mostly run in an empty directory and only assert STDERR, so they do not verify that the rewritten command still executes successfully. Add Behat scenarios for each conversion and assert retained output/exit behavior, plus warning-free --help, --info, and --json cases.
As per coding guidelines, features/**/*.feature: Add Behat acceptance tests for every new feature and bug fix, following existing feature-test patterns.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@features/back-compat.feature` around lines 8 - 46, Expand
features/back-compat.feature with Behat scenarios covering the newly warned
conversions: *-meta, --admin_name, core language, checksum aliases, --site_id,
transient aliases, plugin scaffold, and URL shortcuts. For each, assert the
deprecation warning plus successful rewritten-command output and exit behavior,
and add warning-free coverage for --help, --info, and --json while preserving
the existing shorthand behavior checks.
Source: Coding guidelines
| When I run `wp config create --skip-check` | ||
| And I run `grep WP_POST_REVISIONS wp-config.php` | ||
| Then STDOUT should not be empty |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Update the command-specific config key with the command rename.
The fixture still defines core config: at Lines [204-210], but this scenario now runs wp config create. Runner::run_command() looks up extra configuration by the resolved command name, so the extra-php block may not be applied and the subsequent grep WP_POST_REVISIONS assertion can fail. Rename the fixture key to config create:; add a separate legacy wp core config scenario to test the deprecation warning.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@features/config.feature` around lines 212 - 214, Update the fixture key from
“core config” to “config create” so Runner::run_command() applies the extra-php
configuration to the renamed command. Add a separate legacy “wp core config”
scenario that verifies the deprecation warning.
The "Apply backwards compat conversions" scenario in runcommand.feature runs `term url` through `wp run`, which now emits a deprecation notice on STDERR; assert the notice instead of expecting empty STDERR, and use `try` so the notice does not fail the step. The `core config` config-section scenario keeps using `wp core config` (so the `core config:` config key still matches) and switches to `try` to tolerate the notice. Revert the validation scenarios back to `wp core config`, which already used `try`.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@features/config.feature`:
- Line 212: In the scenario around the “When I try `wp core config
--skip-check`” step, add the existing command-success assertion immediately
afterward and before the following grep command, preserving the return-code 0
check so failures cannot be masked.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 2bf184ad-82bd-4773-b9c8-b83fc4be72ba
📒 Files selected for processing (2)
features/config.featurefeatures/runcommand.feature
Rather than keeping the `core config` deprecated form and switching to `try` to swallow the new notice, update these scenarios to the modern `config create` command. The config-section scenario also renames its wp-cli.yml key from `core config:` to `config create:` so the command-specific config still matches, letting the step stay on `When I run` and keep asserting a clean STDERR. The runcommand "Apply backwards compat conversions" scenario keeps using the deprecated `term url` form on purpose, since testing the conversion (and now its notice) is the point of that scenario.
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Fixes #6353.
What
Runner::back_compat_conversions()silently rewrites a set of pre-1.0 command and flag syntaxes to their modern equivalents. This adds a deprecation warning at each genuinely-legacy conversion site, naming the modern form, while keeping the rewrite working. These syntaxes are scheduled for removal in 4.0.Why
Nothing ever warned about these rewrites, so a user still on an old syntax has no signal that it is outdated. Removing them outright in 3.0 (the original plan) would break scripts with a bare "unknown command" and no pointer to the replacement, for syntaxes we never told anyone were deprecated. Deprecating in 3.0 and removing in 4.0 starts the clock at the major boundary, which is the first time we have ever signalled these are on the way out.
Deprecated in 3.0 (warn, keep working; remove in 4.0)
wp sql,wp blog,wp {post|comment|user|network}-meta,wp cli aliases,wp core config,wp core language,wp checksum core,wp checksum plugin,--admin_name,--site_id,wp {plugin|theme} update-all,wp transient delete-expired,wp transient delete-all,wp plugin scaffold,{post|user} list --ids, andwp {post|comment|site|term} url.Each emits, for example:
Left untouched (permanent features, not legacy)
Per #6353 these stay as they are, with no warning:
wp <command> --help->wp help <command>(this is how--helpis implemented)wp --version/wp --info->wp cli version/wp cli info--json->--format=json(kept as a convenient shorthand)Implementation note
The conversion runs during the
ConfigureRunnerbootstrap step, which is beforeInitializeLogger, soWP_CLI::warning()would be lost at that point. The notice is therefore written straight to STDERR through a smalldeprecated_syntax()helper, matching the existing--blogdeprecation inConfigurator.Out of scope
back_compat_conversions()also rewritesconfig get --global/--constantand bareconfig get->config list. That one was not part of #6353's list, so it is deliberately left alone here. Worth a separate decision on whether to deprecate it too.Tests
features/back-compat.featurecovers a deprecated top-level alias, a deprecated subcommand, a deprecated flag, and asserts a retained shorthand (--version) does not warn.wp cli aliasesscenarios infeatures/aliases.featurenow also assert the deprecation notice.wp core configusages infeatures/config.featureandfeatures/validation.featureswitch towp config createso they are not testing (and warning on) the deprecated alias.Follow-up
The 4.0 removal (turning these into hard errors) is tracked as a task in #6353.
Summary by CodeRabbit
New Features
Bug Fixes
wp --versionremains warning-free.Tests