Skip to content

Rename the content and users abilities and remove ai/get-post-details - #1002

Merged
dkotter merged 6 commits into
developfrom
update/rename-content-users-query-abilities
Sep 9, 2026
Merged

dkotter merged 6 commits into
developfrom
update/rename-content-users-query-abilities

Conversation

@gziolo

@gziolo gziolo commented Sep 4, 2026 •

Copy link
Copy Markdown
Member

What?

Renames two abilities so the names describe what they do, and removes one ability that duplicated the new content query:

  • core/read-content is now core/content-query
  • core/read-users is now core/users-query
  • ai/get-post-details is removed. Use the single-post mode of core/content-query instead.

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-details fetched one post by ID and returned title, slug, content, excerpt, author, and type. The single-post mode of core/content-query returns 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:

  • The ability registrations, unregister guards, labels, and docblocks use the new names.
  • The gated wrapper classes are renamed to Content_Query and Users_Query.
  • The Content ability methods that embedded the old name now use content_query (for example execute_content_query).
  • Integration tests, the e2e helper plugin, and the e2e specs follow the new names. The two spec files are renamed too.

Removal:

  • The ai/get-post-details registration is gone. The gated Post_Utilities wrapper now only registers ai/get-post-terms.
  • The static Posts::get_post_details() helper and its wpai_get_post_details filter stay, because get_post_context() uses them for the generation abilities. The helper tests call the static method directly now.
  • The client-side 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.
  • The Custom Abilities e2e spec now checks the gate through core/content-query.
  • Past entries in CHANGELOG.md and readme.txt keep 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-content and core/read-users are 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 a deprecated entry with the version and the replacement name.
  • ai/get-post-details stays registered with the same deprecation note in its description and meta.
  • Executing any of the three triggers a deprecation notice through _deprecated_function(), so developers see it with WP_DEBUG on.
  • A new register_deprecated_ability_alias() helper in includes/helpers.php builds the aliases, so future renames can reuse it.
  • The aliases are marked with @todo comments for removal after a few releases.

Use of AI Tools

Testing Instructions

  1. Enable the Custom Abilities experiment on the AI settings screen.
  2. Visit /wp-json/wp-abilities/v1/abilities and check that core/content-query and core/users-query are listed. The old names core/read-content, core/read-users, and ai/get-post-details are still listed, with "(deprecated)" in the label and a deprecated entry in the meta.
  3. Run core/read-content with an id and confirm it returns the same result as core/content-query. With WP_DEBUG on, a deprecation notice is logged.
  4. Run the PHP tests:
    npm run test:php -- --filter 'ContentTest|UsersTest|Gated_AbilitiesTest|Custom_AbilitiesTest|Show_In_AbilitiesTest|HelpersTest|PostsTest'
    
  5. Run the e2e specs:
    npm run test:e2e -- tests/e2e/specs/abilities tests/e2e/specs/experiments/custom-abilities.spec.js
    

Changelog Entry

Changed - The core/read-content and core/read-users abilities are renamed to core/content-query and core/users-query. The old names keep working as deprecated aliases for now.
Deprecated - The ai/get-post-details ability. Use the single-post mode of core/content-query instead.

Open WordPress Playground Preview

@github-actions

github-actions Bot commented Sep 4, 2026

Copy link
Copy Markdown

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.


🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

@codecov

codecov Bot commented Sep 4, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.52941% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 75.63%. Comparing base (a7657e1) to head (3fef3b2).

Files with missing lines Patch % Lines
includes/helpers.php 97.56% 1 Missing ⚠️
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     
Flag Coverage Δ
unit 75.63% <98.52%> (+0.08%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@gziolo gziolo self-assigned this Sep 4, 2026
@gziolo gziolo changed the title Rename the content and users abilities to core/content-query and core/users-query Rename the content and users abilities and remove ai/get-post-details Sep 4, 2026
@dkotter

dkotter commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

We could also register the old names as deprecated aliases for one or two releases. What do you think? Is a clean rename fine here, or should we add aliases?

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

@gziolo

gziolo commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

Thanks for the input, that is a fair point about two breaking changes in a row. I went with the alias route.

  • core/read-content and core/read-users are now deprecated aliases. They copy the replacement ability and forward execution and permission checks to it.
  • ai/get-post-details stays registered with a deprecation note.
  • All three trigger a deprecation notice through _deprecated_function() when executed, and their meta carries a deprecated entry with the version and the replacement name.
  • A small register_deprecated_ability_alias() helper builds the aliases, so we can reuse it for future renames.

I marked the aliases with @todo comments so we can remove them after a few releases. Let me know if you would rather see a fixed target version.

@gziolo
gziolo marked this pull request as ready for review September 8, 2026 09:21
@gziolo
gziolo requested a review from a team September 8, 2026 09:21
@gziolo
gziolo requested a review from jeffpaul as a code owner September 8, 2026 09:21
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown

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 props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>

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.
@gziolo
gziolo force-pushed the update/rename-content-users-query-abilities branch from c03e8af to 3fef3b2 Compare September 8, 2026 09:34
@dkotter dkotter added this to the 1.4.0 milestone Sep 9, 2026
@dkotter
dkotter merged commit d9f9697 into develop Sep 9, 2026
27 of 33 checks passed
@dkotter
dkotter deleted the update/rename-content-users-query-abilities branch September 9, 2026 14:11
@justlevine

justlevine commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

(I know this already merged, but as there's no matching GH issue for this that I see, so leaving the feedback here)

  • I fail to see how *-query is a better pattern than get-* which is what core currently uses, even if it's better than read-* (Both still fall short when compared to slug fragments 🤷)
  • Regarding breaking changes, I'd also recommend using ai/* as the namespace instead of core/, both because
    • it's in the AI plugin,
    • if these ever do make it to WordPress core with this naming structure intact (full disclosure I'll be fighting hard against), that would allow us to prevent another breaking change and give us a better way to handle the migration path since we'll have the ai/* alias.

Recommending instead:

  • ai/get-user-data (until an eventual merge as core/user/get )
  • ai/get-post-object-data (until an eventual merge core/post-object/get. Separately, I would love if we could redo the last decade of WP and the "Everything is a Post", but until we can think of a holistic reason as to why a Category description, Product Brand image, or any other taxonomic meta data isn't also "content", IMO there's no responsible way to use that word in reference to WP_Post and not WP_Post->post_content)

whyisjake added a commit that referenced this pull request Sep 11, 2026
#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>
whyisjake added a commit that referenced this pull request Sep 11, 2026
#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>
whyisjake added a commit that referenced this pull request Sep 23, 2026
#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>
whyisjake added a commit that referenced this pull request Sep 23, 2026
#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>
jorgefilipecosta added a commit to jorgefilipecosta/wordpress-develop that referenced this pull request Oct 5, 2026
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.
jorgefilipecosta added a commit to jorgefilipecosta/wordpress-develop that referenced this pull request Oct 7, 2026
…ery`.

This matches the name and label that the AI plugin uses since
WordPress/ai#1002.
jorgefilipecosta added a commit to jorgefilipecosta/wordpress-develop that referenced this pull request Oct 12, 2026
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.
jorgefilipecosta added a commit to jorgefilipecosta/wordpress-develop that referenced this pull request Oct 12, 2026
…ery`.

This matches the name and label that the AI plugin uses since
WordPress/ai#1002.
jorgefilipecosta added a commit to jorgefilipecosta/wordpress-develop that referenced this pull request Oct 13, 2026
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.
jorgefilipecosta added a commit to jorgefilipecosta/wordpress-develop that referenced this pull request Oct 14, 2026
…ery`.

This matches the name and label that the AI plugin uses since
WordPress/ai#1002.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants