[wp-trac] [WordPress Trac] #64209: Allow abilities to be deprecated

[WordPress Trac]

#64209: Allow abilities to be deprecated
--------------------------+---------------------
 Reporter:  jorbin        |       Owner:  (none)
     Type:  defect (bug)  |      Status:  new
 Priority:  normal        |   Milestone:  7.0
Component:  AI            |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:
--------------------------+---------------------

Comment (by justlevine):

 Only saw this ticket tonight (thanks @jason_the_adams ), and wanted to
 share a few quick thoughts before I find time to look at everything more
 deeply:

 1. I think this should be considered an enhancement, not a "bug", and
 definitely not rushed into 6.9.x. I don't remember if this was ever
 discussed explicitly (cc @gziolo ), but at least on my part it was an
 intentional exclusion, and if it was brought up I'd have advocated against
 inclusion to let the API continue to evolve holistically despite the short
 initial merge window. As mentioned by others, existing `_deprecated_*()`,
 and `_doing_it_wrong()`, and several other ways established ways exist to
 communicate deprecations and API changes. Imperfect parallel, but AFAIK
 there's no explicit way to deprecate a REST endpoint for example, you
 don't even get a notice if you're hitting a `v1/endpoint` when a
 `v2/endpoint` has also been registered).

 2. I don't think versioning - on its own at least, but maybe altogether? -
 is an ideal approach for this sort of API (I know we keep comparing it to
 REST, but IMO it's a lot more similar to Hooks, and REST becomes
 conceptually just an Adapter around a bunch of Abilities). Also
 anecdotally, most plugins I've seen and developers I've worked with don't
 seem to rely on REST or Blocks beyond WP core and a few "trusted" plugins,
 and I assume the same lack of version hygiene would limit anything
 programmatic (and we already have ways to inform users of changes that
 don't require a specific API).

 3. Deprecating an entire ability is IMO the _least_ needing of a specific
 API (because, again, preexisting solutions). Much more urgent IMO are
 communicating granular deprecations that allow an ability to remain long-
 lived and evolve over time: input/output fields. I'm a big fan of
 WPGraphQL's versionless `array{deprecationReason?:string,
 ...otherRegisterArgs}` [https://www.wpgraphql.com/recipes/deprecating-a
 -field-in-the-schema Deprecation API] and was planning to suggest a
 similar pattern here (and still plan to once I have fresh eyes).
 Versionless also jive's more with Core's general aversion to breaking
 changes. And as much as I _hate_ to use AI as a reason for anything, it's
 a much friendlier pattern for overcoming the stale/training data problem
 with LLMs.

 4. All that said, I'm liking the direction @jason_the_adams's draft PR in
 the very quick glance I took. Because of my aversion to versioning, I'd
 probably recommend we start out with `meta.deprecated?: string|null`. This
 would also let downstream experimentation or usage of explicit versioning
 for developers who prefer it (this would pair well if we decided to relax
 the [https://github.com/WordPress/wordpress-
 develop/blob/f2212d933387ca23d59451e4c2a6413a7d5c1769/src/wp-includes
 /abilities-api/class-wp-abilities-registry.php#L81 only-one-forwardslash
 name requirement], which I thought we already did before the beta1 merge
 😅). That said **if we know we're gonna have multiple props**, then I
 agree we should go with the array structure (ideally sharing the pattern
 used by inputs/outputs, another reason why IMO we should take as much time
 as needed to think about this holistically). Even w.o PHPStan array
 shapes, we're already nested so we're not losing any tooling vs a "top-
 level" `meta.{deprecation_property}`.

 Anywhoo, I'll come back when I'm not sleep deprived and on deadline, but
 hopefully I made enough sense to at least buy me some time before y'all
 agree to try and quickly push something into 6.9rcx 🙏🤞😴

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