Repository navigation
Improve documentation of unreleased changes #666
Description
Bug Report
- Yes, I reviewed the contribution guidelines.
- Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.
Describe the current, buggy behavior
The block command still enumerated in the online docs despite not being available in the live build of the CLI. I reported this on the 28th of April (see wp-cli/wp-cli-bundle#1002) and was told at the time that the new release was, "around the corner". It has been 4.5 months. The documentation that incorrectly asserts that the block command is available has been live since mid December of 2025 (roughly nine months ago).
Describe how other contributors can replicate this bug
- Go to https://developer.wordpress.org/cli/commands/block/
- Observe that the page you went to is live
- https://developer.wordpress.org/cli/commands/
- Observe that it provides a link to that page in the third row of the table enumerating available commands
Describe what you would expect as the correct outcome
I expect the documentation to enumerate the available commands in the currently-live version of the CLI.
Let us know what environment you are running this on
OS: Linux 4.14.318-241.531.amzn2.x86_64 wp-cli/wp-cli-bundle#1 SMP Tue Jun 27 21:49:00 UTC 2023 x86_64
Shell: /bin/bash
PHP binary: /usr/local/bin/php
PHP version: 8.5.6
php.ini used: /usr/local/etc/php/php.ini
MySQL binary: /usr/bin/mariadb
MySQL version: mariadb from 11.8.6-MariaDB, client 15.2 for debian-linux-gnu (x86_64) using EditLine wrapper
SQL modes:
WP-CLI root dir: phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir: phar://wp-cli.phar/vendor
WP_CLI phar path: phar:///usr/local/bin/wp
WP-CLI packages dir:
WP-CLI cache dir: /home/joshualip/.wp-cli/cache
WP-CLI global config:
WP-CLI project config:
WP-CLI version: 2.12.0
Provide a possible solution
I would recommend that the documentation be updated to not list alpha/beta commands or, if that is not an option, to at least mark the listed alpha/beta commands as available only in the alpha/beta.
Activity
swissspidy commentedon Oct 6, 2026
Thanks for your report (again). I understand the confusion and frustration, but I suggest we rather invest the time in shipping the new release instead of temporarily updating our documentation automation.
I recommend updating to updating to the current nightly build, which is very stable at this point.
joshualip-plaudit commentedon Oct 8, 2026
@swissspidy I understand that software takes a while to ship - I'm taking issue with the documentation being off, not things needing more time in the oven.
For context, I made this task because I got bug report from a coworker due to them trying to use the blocks command. My recommendation (in order to mitigate this issue in the future - not as a one-off) is that the documentation automation be updated to either exclusively use release cuts (as determined by GitHub's system, some sort of tag-checking, etc) or have support for "beta" markers added (and then have this scheme shared with Gutenberg specifically).
This is an issue with a few WordPress projects, not just with wp-cli - I've seen it happen a couple of times with Gutenberg, but it's not as big of a deal there because they use a more incremental shipping strategy, so the docs rarely have more than a day or two of lead time against the latest available versions, and because their docs have other far more severe problems, so it's not as obvious.
[-]The [block] command STILL does not actually exist[/-][+]Improve documentation of unreleased changes[/+]Flag commands and options not in the latest stable release (#668)
Show in which release commands and options first appeared (#669)
swissspidy commentedon Oct 11, 2026
Added a disclaimer to the docs now to mention this, hope that helps.
joshualip-plaudit commentedon Oct 12, 2026
That helps a lot! Thank you!