[wp-trac] [WordPress Trac] #64345: Ability names should support versioning

[WordPress Trac]

#64345: Ability names should support versioning
--------------------------------------+---------------------
 Reporter:  jason_the_adams           |       Owner:  (none)
     Type:  enhancement               |      Status:  new
 Priority:  normal                    |   Milestone:  7.1
Component:  Abilities API             |     Version:
 Severity:  normal                    |  Resolution:
 Keywords:  has-patch has-unit-tests  |     Focuses:
--------------------------------------+---------------------
Changes (by gziolo):

 * keywords:  has-patch, has-unit-tests => has-patch has-unit-tests


Comment:

 I think backward compatibility should be the primary lens for this ticket.
 Abilities are public contracts between Core, plugins, themes, JS clients,
 and other consumers, similar to REST routes, hooks, functions, and
 classes. Once published, consumers may depend on them directly, so the
 ability name should remain a stable identifier for the capability rather
 than encode the version of its schema or implementation.

 That also matches how the REST API is handled in practice. Core REST
 routes are long-lived and usually evolve additively, with new parameters
 and response fields added over time rather than replacing URLs for routine
 changes. Abilities should follow the same principle.

 I would therefore avoid making version segments such as `plugin/v1/do-
 thing` part of the ability naming model. This also becomes awkward when
 exposed through REST:

 `/wp-json/wp-abilities/v1/abilities/plugin/v2/do-thing`

 That reads like overlapping versioning systems: the REST route already has
 its own versioned namespace, while the ability name should identify the
 capability itself.

 For schema changes, we should still allow a compatibility path. Individual
 input or output properties can be soft-deprecated where needed, similar to
 how REST API fields or parameters can remain supported while being marked
 as deprecated. If a truly different capability is introduced, it should
 get a new semantic ability name rather than a numbered version. It's also
 where formal deprecation (#64209) could help.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64345#comment:22>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform