Add declarative deprecation handling for commands and assoc args by Copilot · Pull Request #6343 · wp-cli/wp-cli

Copilot · 2026-07-16T09:16:21Z

This introduces framework-level deprecation handling based on command docblocks and argument YAML metadata, so command authors no longer need to manually emit warnings. Deprecated commands/args are now surfaced consistently in both help output and runtime execution paths.

Command-level deprecation from PHPDoc
- Added DocParser::get_deprecation_message() to parse @deprecated ....
- Subcommand::invoke() now emits a warning before execution when the command is marked deprecated.
Argument-level deprecation from synopsis YAML
- Added assoc-arg deprecation extraction in Subcommand from option metadata:
  - deprecated: <message>
- Emits warning only when a deprecated argument is actually provided by the user.
Help output integration
- Help_Command now appends a deprecation sentence in SYNOPSIS for deprecated commands.
- Argument deprecation messages are injected into option descriptions in help output.
Coverage updates
- Added unit coverage for @deprecated parsing in DocParserTest.
- Added feature coverage for command + argument deprecation behavior in features/command.feature.

/**
 * Deprecated command.
 *
 * ## OPTIONS
 *
 * [--old=<old>]
 * : Old parameter.
 * ---
 * deprecated: Use `--new` instead.
 * ---
 *
 * @deprecated Use `wp replacement` instead.
 */

With this, help includes deprecation guidance and runtime prints warnings before invoking deprecated command paths.

Summary by CodeRabbit

New Features
- Added support for declaring deprecated commands and arguments via command annotations.
- Help output now surfaces command- and argument-level deprecation details, including optional guidance.
Behavior Updates
- Deprecation warnings are emitted only when the corresponding deprecated commands or options/arguments are actually used (including during prompt flows), while still allowing successful execution.
Tests
- Expanded help and deprecation parsing coverage to verify messaging and warning behavior.

codecov · 2026-07-16T09:20:55Z

Codecov Report

❌ Patch coverage is 19.75309% with 65 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
php/commands/src/Help_Command.php	0.00%	39 Missing ⚠️
php/WP_CLI/Dispatcher/Subcommand.php	0.00%	24 Missing ⚠️
php/WP_CLI/DocParser.php	88.88%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

Co-authored-by: swissspidy <[email protected]>

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

…nt YAML block from Options Co-authored-by: swissspidy <[email protected]>

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Co-authored-by: swissspidy <[email protected]>

coderabbitai

🧹 Nitpick comments (1)

php/WP_CLI/DocParser.php (1)
141-145: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Cover the explicit deprecated: false branch with a regression test.

Current tests cover non-empty and empty-string messages, but not the newly introduced behavior that explicitly disabled metadata is ignored. Add a fixture asserting deprecated: false is omitted from the returned map.
🤖 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 `@php/WP_CLI/DocParser.php` around lines 141 - 145, Add a regression fixture
for the deprecation parsing flow in DocParser, asserting that an argument with
explicit deprecated: false is omitted from the returned map. Keep existing
coverage for non-empty and empty-string deprecated messages unchanged.

🤖 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.

Nitpick comments:
In `@php/WP_CLI/DocParser.php`:
- Around line 141-145: Add a regression fixture for the deprecation parsing flow
in DocParser, asserting that an argument with explicit deprecated: false is
omitted from the returned map. Keep existing coverage for non-empty and
empty-string deprecated messages unchanged.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d06dcab1-fa4d-4d3a-a960-e6cebe0805bd

📥 Commits

Reviewing files that changed from the base of the PR and between baacc30 and 43a1716.

📒 Files selected for processing (5)

features/command.feature
php/WP_CLI/Dispatcher/Subcommand.php
php/WP_CLI/DocParser.php
php/commands/src/Help_Command.php
tests/DocParserTest.php

🚧 Files skipped from review as they are similar to previous changes (4)

php/commands/src/Help_Command.php
tests/DocParserTest.php
php/WP_CLI/Dispatcher/Subcommand.php
features/command.feature

Covers the branch in `DocParser::get_deprecated_assoc_args()` where an explicit `deprecated: false` marks an argument as not deprecated, so it is omitted from the returned map. Complements existing coverage for the non-empty and empty-string deprecation messages. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Initial plan

0ede917

Copilot AI assigned Copilot and swissspidy Jul 16, 2026

Copilot started work on behalf of swissspidy July 16, 2026 09:16 View session

Copilot AI linked an issue Jul 16, 2026 that may be closed by this pull request

Declarative way to mark commands and arguments deprecated #6342

Closed

github-actions Bot added command:cli Related to 'cli' command command:cli-help command:cli-utils labels Jul 16, 2026

Add declarative command and argument deprecation support

0da3160

Co-authored-by: swissspidy <[email protected]>

Copilot AI changed the title ~~[WIP] Add a declarative way to mark commands and arguments deprecated~~ Add declarative deprecation handling for commands and assoc args Jul 16, 2026

Copilot finished work on behalf of swissspidy July 16, 2026 09:26

Copilot AI requested a review from swissspidy July 16, 2026 09:26

swissspidy reviewed Jul 16, 2026

View reviewed changes

Comment thread features/command.feature Outdated

Apply suggestion from @swissspidy

cec11eb

This comment was marked as resolved.

Sign in to view

swissspidy requested a review from Copilot July 16, 2026 10:06

Copilot started reviewing on behalf of swissspidy July 16, 2026 10:07 View session

This comment was marked as resolved.

Sign in to view

swissspidy and others added 3 commits July 16, 2026 12:28

Potential fix for pull request finding

ef25387

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Potential fix for pull request finding

365fdbd

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

Potential fix for pull request finding

0f2ebac

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

swissspidy reviewed Jul 16, 2026

View reviewed changes

Comment thread php/commands/src/Help_Command.php Outdated

Apply suggestion from @swissspidy

8c34507

swissspidy reviewed Jul 16, 2026

View reviewed changes

Comment thread features/command.feature Outdated

Apply suggestion from @swissspidy

458c8ff

This comment was marked as resolved.

Sign in to view

Copilot started work on behalf of swissspidy July 16, 2026 10:59 View session

Move command deprecation notice to DESCRIPTION section; strip redunda…

9d91d20

…nt YAML block from Options Co-authored-by: swissspidy <[email protected]>

This comment was marked as resolved.

Sign in to view

Potential fix for pull request finding

e0ada5e

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

This comment was marked as resolved.

Sign in to view

Copilot started work on behalf of swissspidy July 16, 2026 13:30 View session

Revert YAML-stripping in help output for deprecated args

cebb90d

Co-authored-by: swissspidy <[email protected]>

This comment was marked as resolved.

Sign in to view

Copilot finished work on behalf of swissspidy July 16, 2026 13:32

swissspidy marked this pull request as ready for review July 16, 2026 13:40

swissspidy requested a review from a team as a code owner July 16, 2026 13:40

This comment was marked as resolved.

Sign in to view

swissspidy added 2 commits July 20, 2026 12:08

Address code review feedback

baacc30

Merge branch 'main' into copilot/add-deprecation-checks

aabfc05

swissspidy added this to the 3.0.0 milestone Jul 20, 2026

schlessera reviewed Jul 20, 2026

View reviewed changes

Comment thread php/WP_CLI/DocParser.php Outdated

Comment thread php/commands/src/Help_Command.php Outdated

Comment thread php/WP_CLI/Dispatcher/Subcommand.php

schlessera requested changes Jul 20, 2026

View reviewed changes

swissspidy added 6 commits July 20, 2026 19:02

Merge branch 'main' into copilot/add-deprecation-checks

a4a5435

Improve regex

9fb0efd

Check for empty tags

76f3235

Handle deprecated arg without description

7e0c9cf

Use has_tag to check for deprecation messages

398c7e5

Update tests

43a1716

coderabbitai Bot reviewed Jul 20, 2026

View reviewed changes

schlessera approved these changes Jul 21, 2026

View reviewed changes

schlessera mentioned this pull request Jul 21, 2026

Wait for both coverage uploads before reporting to Codecov #6348

Merged

swissspidy merged commit 0c9cf6a into main Jul 21, 2026
73 of 74 checks passed

swissspidy deleted the copilot/add-deprecation-checks branch July 21, 2026 06:13

This was referenced Jul 21, 2026

Deprecate legacy back_compat_conversions syntaxes in 3.0.0, remove in 4.0.0 #6353

Closed

Deprecate plugin status and theme status commands wp-cli/extension-command#534

Merged

coderabbitai Bot mentioned this pull request Jul 31, 2026

Significant PHPStan improvements #6366

Merged

coderabbitai Bot mentioned this pull request Aug 13, 2026

Synopsis: Support uppercase letters in arguments for completion #6388

Merged

Navigation Menu

Repository navigation

Add declarative deprecation handling for commands and assoc args - #6343

Add declarative deprecation handling for commands and assoc args#6343
swissspidy merged 20 commits into
mainfrom
copilot/add-deprecation-checks

Copilot AI commented Jul 16, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

codecov Bot commented Jul 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented Jul 16, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

codecov Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jul 16, 2026 •

edited by coderabbitai Bot

Loading

codecov Bot commented Jul 16, 2026 •

edited

Loading