The answer to the topic of this task for the Action API has traditionally been "to mediawiki-api-announce when the relevant patch is merged".

The closest to a deprecation policy for the Action API is https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap#Deprecation_process. There are no stability guarantees beyond what's in there.

Of course, it's not always feasible to completely follow it (e.g. for the recent ParamValidator error code change). The message to wikitech-l about that recent ParamValidator error code change was requested by WMDE.

I think it would be great if we had aligned policies and processes. For changes performed by WMDE related to Wikidata, we apply our policy with, in the case of a breaking change, a certain process to follow and a minimum amount of time between announcement and deployment. On the other hand, mediawiki-api-announce ML is not part of this process and should probably be.

Since we’re already using the mediawiki-api-announce mailing list in a few places, I’d recommend applying this process more widely and more explicitly as the primary channel for communicating updates to MediaWiki APIs and related APIs. To keep this reply short, I’ve posted my full notes in a wiki page.

I’d suggest the following documentation updates:

• For the Action API, create a page within the Action API docs with the deprecation policy from the API roadmap RFC. (See proposed text.) Reference this page from the Action API FAQ, and add mediawiki-api-announce to the footer on the API main page.
• For the RESTBase API, update the versioning policy to clarify that mediawiki-api-announce will be used as the communication channel for breaking changes to unstable endpoints and for non-breaking updates and announcements.
• For the MediaWiki REST API, update the main page to specify that mediawiki-api-announce will be used as the communication channel for API updates.
• For the Wikidata stable interface policy, add mediawiki-api-announce to the list of notification channels for updates to stable public APIs.

In addition, here are a few other things to consider:

• Addressing stability guarantees for the Action API in RFC stable interface policy
• Experiment with announcing API updates through tech news
• Referencing API update policies on the Action API extensions and MediaWiki REST API extensions docs

I don't object to announcing of breaking changes to other APIs (besides the Action API) to mediawiki-api-announce. But it's intended to be a low-traffic announcements mailing list, so IMO we should strictly limit announcement of updates that aren't breaking changes.

Non-breaking updates can still be announced through other channels, including Tech News and the mediawiki-api mailing list.

Thanks for your comments both here and on the wiki page, @Anomie! I've updated the task description with an updated proposal that maintains mediawiki-api-announce as a low traffic list for breaking changes only. The updated draft for the Action API change policy can be found here. Further feedback is very welcome!

Thanks! The rest of it looks fine to me, or is outside the scope of things I know much about.

@apaskulin Can we close this?

My apologies, I haven't gotten a chance to do this yet, so it should stay open for now. Feel free to untag Clinic Duty.

@apaskulin let's discuss what the next steps with this are.