Repository navigation
Rename the content and users abilities and remove ai/get-post-details - #1002
Conversation
✅ WordPress Plugin Check Report
📊 ReportAll checks passed! No errors or warnings found. 🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## develop #1002 +/- ##
=============================================
+ Coverage 75.55% 75.63% +0.08%
Complexity 3381 3381
=============================================
Files 138 138
Lines 13081 13129 +48
=============================================
+ Hits 9883 9930 +47
- Misses 3198 3199 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Personally I'd suggest going the alias route here as we already shipped a breaking change with these abilities in the last release so anyone using these would have to deal with breaking changes two releases in a row. That said, these are now behind an experiment toggle and we don't claim to provide backwards compat for experiments so could be justified in not doing that |
|
Thanks for the input, that is a fair point about two breaking changes in a row. I went with the alias route.
I marked the aliases with |
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
…/users-query The names now describe what the abilities do: they query content or users. The gated wrapper classes, the Content ability methods, and the e2e specs follow the new names.
The single-post mode of core/content-query returns the same data with better access rules. The static Posts::get_post_details() helper stays, because get_post_context() and its filter still use it. The client-side getContext() helper in image generation was unused, so it is removed too. The Custom Abilities e2e spec now checks the gate through core/content-query.
core/read-content and core/read-users are registered again as aliases that copy the replacement ability and forward calls to it. ai/get-post-details stays registered with a deprecation note. Executing any of them triggers a deprecation notice. The aliases can be removed after a few releases. A new register_deprecated_ability_alias() helper builds the aliases so the same approach can be reused for future renames.
c03e8af to
3fef3b2
Compare
|
(I know this already merged, but as there's no matching GH issue for this that I see, so leaving the feedback here)
Recommending instead:
|
#1002 renamed core/read-users to core/users-query and kept the old name as a deprecated alias. Both are registered, and the withheld list named only the old one -- so the ability it exists to hold back was reachable under the name core now prefers. Not reachable in practice yet: core/users-query is not public and does not assert an admissible effect class. But the point of the list is to hold when those change, and it was not holding. Both names are listed, because the alias is a real registration rather than a redirect. A rename upstream is a hole here until someone adds the new name, which the docblock now says. PHPStan goes with it. The composer script pinned 1G, and this branch pushed analysis past it once develop merged in, so the documented command crashed. 2G clears it. CI never used that script -- it runs phpstan with no limit at all -- so this is the local command catching up to what CI already did. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#1002 renamed core/read-content to core/content-query. Nine docblock and doc references here still pointed at the old name, which now resolves to a deprecated alias -- accurate enough to pass review and wrong enough to send the next reader somewhere that will be removed. The withheld list keeps naming both sides of the users rename, and the docs now say why: the alias is a real registration that copies the replacement's meta, so exposure changes reach both names at once and holding back only one holds back nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#1002 renamed core/read-users to core/users-query and kept the old name as a deprecated alias. Both are registered, and the withheld list named only the old one -- so the ability it exists to hold back was reachable under the name core now prefers. Not reachable in practice yet: core/users-query is not public and does not assert an admissible effect class. But the point of the list is to hold when those change, and it was not holding. Both names are listed, because the alias is a real registration rather than a redirect. A rename upstream is a hole here until someone adds the new name, which the docblock now says. PHPStan goes with it. The composer script pinned 1G, and this branch pushed analysis past it once develop merged in, so the documented command crashed. 2G clears it. CI never used that script -- it runs phpstan with no limit at all -- so this is the local command catching up to what CI already did. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#1002 renamed core/read-content to core/content-query. Nine docblock and doc references here still pointed at the old name, which now resolves to a deprecated alias -- accurate enough to pass review and wrong enough to send the next reader somewhere that will be removed. The withheld list keeps naming both sides of the users rename, and the docs now say why: the alias is a real registration that copies the replacement's meta, so exposure changes reach both names at once and holding back only one holds back nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Renames the ability from `core/read-content` to `core/content-query` to match the AI plugin (WordPress/ai#1002), and ports the plugin's lean projection test, which checks the query arguments the ability builds instead of counting post meta queries. Also drops the trailing period from the hook documentation references, which the PHPStan hook docblock rule reads as part of the file path.
…ery`. This matches the name and label that the AI plugin uses since WordPress/ai#1002.
Renames the ability from `core/read-content` to `core/content-query` to match the AI plugin (WordPress/ai#1002), and ports the plugin's lean projection test, which checks the query arguments the ability builds instead of counting post meta queries. Also drops the trailing period from the hook documentation references, which the PHPStan hook docblock rule reads as part of the file path.
…ery`. This matches the name and label that the AI plugin uses since WordPress/ai#1002.
Renames the ability from `core/read-content` to `core/content-query` to match the AI plugin (WordPress/ai#1002), and ports the plugin's lean projection test, which checks the query arguments the ability builds instead of counting post meta queries. Also drops the trailing period from the hook documentation references, which the PHPStan hook docblock rule reads as part of the file path.
…ery`. This matches the name and label that the AI plugin uses since WordPress/ai#1002.
What?
Renames two abilities so the names describe what they do, and removes one ability that duplicated the new content query:
core/read-contentis nowcore/content-querycore/read-usersis nowcore/users-queryai/get-post-detailsis removed. Use the single-post mode ofcore/content-queryinstead.Why?
Both renamed abilities query a set of items with filters and pagination, or fetch a single item. "Query" describes this better than "read". It also lines up with the query-style naming used elsewhere in WordPress.
ai/get-post-detailsfetched one post by ID and returned title, slug, content, excerpt, author, and type. The single-post mode ofcore/content-queryreturns the same data plus more, with read-level access rules instead of requiring edit access. Keeping both meant two ways to do the same thing.How?
Rename:
Content_QueryandUsers_Query.content_query(for exampleexecute_content_query).Removal:
ai/get-post-detailsregistration is gone. The gatedPost_Utilitieswrapper now only registersai/get-post-terms.Posts::get_post_details()helper and itswpai_get_post_detailsfilter stay, becauseget_post_context()uses them for the generation abilities. The helper tests call the static method directly now.getContext()helper in the image generation feature was not used anywhere, so it is deleted.generateImage()already reads the title and type from the editor store.core/content-query.CHANGELOG.mdandreadme.txtkeep the old names because they describe released versions.Deprecated aliases
The old names keep working for a few releases, so nobody has to deal with a second breaking change right away:
core/read-contentandcore/read-usersare registered as deprecated aliases. Each alias copies the label, description, category, schemas, and meta of its replacement, and forwards execution and permission checks to it. The description starts with a "Deprecated" note, and the meta carries adeprecatedentry with the version and the replacement name.ai/get-post-detailsstays registered with the same deprecation note in its description and meta._deprecated_function(), so developers see it withWP_DEBUGon.register_deprecated_ability_alias()helper inincludes/helpers.phpbuilds the aliases, so future renames can reuse it.@todocomments for removal after a few releases.Use of AI Tools
Testing Instructions
/wp-json/wp-abilities/v1/abilitiesand check thatcore/content-queryandcore/users-queryare listed. The old namescore/read-content,core/read-users, andai/get-post-detailsare still listed, with "(deprecated)" in the label and adeprecatedentry in the meta.core/read-contentwith anidand confirm it returns the same result ascore/content-query. WithWP_DEBUGon, a deprecation notice is logged.Changelog Entry