[wp-trac] [WordPress Trac] #52629: Introduce a better way to deprecate REST API parameters

[WordPress Trac]

#52629: Introduce a better way to deprecate REST API parameters
----------------------------+-----------------------------
 Reporter:  SergeyBiryukov  |      Owner:  (none)
     Type:  defect (bug)    |     Status:  new
 Priority:  normal          |  Milestone:  Awaiting Review
Component:  REST API        |    Version:
 Severity:  normal          |   Keywords:
  Focuses:                  |
----------------------------+-----------------------------
 Background: #52192.

 [50124] introduced new endpoints to allow for batch image editing using
 the REST API, and soft-deprecated some older parameters. Splitting this
 out from #52192 to figure out a more formal way to deprecate them.

 @SergeyBiryukov, comment:17:ticket:52192:
 >> DEPRECATED: Use `modifiers` instead
 >
 > Putting this in translatable descriptions doesn't seem to follow any
 other patterns in core. Is that necessary? Is there anything wrong with
 using the older format, apart from the newer one taking precedence?
 >
 > If we want everyone to stop using the older format, could we call
 `_deprecated_argument()` instead when any of these older arguments are
 used? That would also allow us to specify the version in which they were
 deprecated.
 >
 > At the very least, `modifiers` should be moved out of the translatable
 strings and replaced with a placeholder, to prevent it from being
 translated.
 >
 > I think these changes would also benefit from `@since` tags on the
 affected methods.

 TimothyBlynJacobs, comment:19:ticket:52192:
 > AFAIK, we haven't deprecated any REST API parameters yet, this is the
 first. At a later point I plan on adding a more formal `deprecated` syntax
 that we could apply to the parameter schemas. So at the moment, this is
 just a soft deprecation.
 >
 > The problem generally is that we don't have a good way to generate
 changelogs for the REST API. We could add `@since` markers, but they
 aren't picked up by the [https://developer.wordpress.org/rest-
 api/reference/ REST API reference] documentation. We also haven't really
 done this in the past. AFAICT the only usages are in
 `WP_REST_Posts_Controller::get_collection_params()`. Ideally, we'd make
 this available in the schema definition for each parameter.
 >
 > Putting `Deprecated` in the parameter description means that it will be
 picked up by the REST API reference. Though for some reason, the edit
 endpoint isn't being picked up at all. I'll take a look at that when we
 regenerate our docs for 5.7.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/52629>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform