The same procedures could also be potentially applied to internal interfaces commonly used by extensions and skins, which becomes particularly relevant when you consider how we encourage third party wikis write their own extensions for their own use cases, and the only way to make a custom theme (skin) is to use these interfaces as well.

Removing Team-Practices; it doesn't seem to fall within our scope.

This task is mainly about agreeing on expectations on the developers changing APIs, right?

• How much effort are they expected to put discussing changes with the users of their APIs?
• How much effort are they expected to put keeping backward compatibility?
• How much effort are they expected communicating changes beyond mediawiki-api-announce?
• How much effort are they expected to put in fixing community-maintained software breaking after the change?

Also, what are the expectations on WMF's Community Engagement and Community Tech to communicate changes and fix broken software?

In T114384#1754743, @Qgil wrote:

This task is mainly about agreeing on expectations on the developers changing APIs, right?

This is a big part of it, yes. Another part is making it easier for community developers to update gadgets written by other people by keeping track of gadget usage and of instances of deprecated code.

Was this topic discussed at the Summit?

In T114384#1927029, @Qgil wrote:

Was this topic discussed at the Summit?

No, it didn't have its own session, and it wasn't discussed otherwise, as far as I'm aware.

Recent wikitech-l discussion about deprecation policies (wikitech-l: Legacy wikibits will no longer loaded by default on Wikimedia wikis and MediaWiki 1.27)

Some comments:

API can be used in multiple senses:

• web APIs (api.php and the RESTBase APIs)
• the signatures of core PHP methods that extension PHP code is supposed to invoke
• the signatures of JS methods that gadgets are supposed to invoke

(Probably less confusing to call the latter two interfaces, but technically they are APIs.) mediawiki-api[-announce] is dedicated for the first; PHP interface changes are typically announced on mediawiki-announce and maybe on wikitech-l (and major changes in the release notes), and JS interface changes on wikitech-ambassadors, and maybe Tech News. The Notice system might also be used for all three kinds of changes, but it's not done consistently.

All three of those APIs are public-facing in some sense of the work, but the public they are facing is very different.

• For PHP interface changes the audience is third-party MediaWiki site owners and developers, who tend to be harder to reach with announcements. (Also other Wikimedia teams, but we have methods for that - Scrum of Scrums, internal lists etc.) They are affected by web API and JS interface changes as well, but probably to a much smaller extent than Wikimedia tool developers. They usually don't have expectations about unmaintained code staying functional forever; they are also somewhat more in control since they can just choose not to update.
• For JS API changes the audience is the gadget community (mostly Wikipedia admins). There is lots of unmaintained code (which probably won't change until gadget sharing features are improved). Fixing other people's stuff is much easier than for extensions or Tool labs tools so people with sufficient knowledge sometimes rally to save broken unmaintained stuff. In my experience, long deprecation times offer no benefit here: activity happens right after announcements, or when stuff breaks. (Frequent announcements probably would help.)
• For web API changes the audience is the Wikimedia tool developer community (including gadgets) plus external clients of the Wikimedia APIs. We have near-zero knowlegde of the latter group (e.g. whether they tend to read mediawiki-api-announce).
• There is also the SQL schema interface: schema changes break some Tool Labs tools. The current expectation seems to be that tool owners will just have to cope with that and there is no deprecation or announcement system. (OTOH schema changes are quite rare.)

I think for PHP interfaces and for api.php it's fairly standard to deprecate (ie. show warnings) and then remove in the next MediaWiki release. That's 6 months from the POV of an end user who installs new releases as they come out (it could be anywhere between 1-12 from the POV of the developer merging the patches).
@demon pointed out recently that this practice is somewhat uncomfortable for the users of LTS releases who are more concerned about stability and only upgrade when new LTS releases come out, every 24 months, so backporting deprecations to the LTS release might be helpful (when practical - often it's not). That's not a standard procedure currently, AFAIK.

There is often a significant amount of developer time spent on killing or fixing individual not-well-maintained bots after web API changes. (I imagine gadgets are less problematic because they cannot misbehave in critical way (e.g. go crazy and send 1000 requests per second), and some bots are critical infrastructure but unmaintained which is less often true for gadgets where the code is public.) This probably overlaps a fair bit with @bd808's tool labs community strengthening project, but it would be nice to have guidelines on what notification efforts are expected before stopping/banning problematic bots.

In T114384#2572920, @Tgr wrote:

This probably overlaps a fair bit with @bd808's tool labs community strengthening project, but it would be nice to have guidelines on what notification efforts are expected before stopping/banning problematic bots.

Labs-announce and/or labs-l should reach all active bot developers for major announcements. Ideally bot developers will also be subscribed to mediawiki-api-announce and wikitech-l. Abandonware bots are what they are and will break.

I'm of the opinion that on-wiki admins should block misbehaving bots as quickly as possible and then reach out to the bot owner(s) via the bot's talk page. I think most of us with super powers in Tool Labs are also happy to stop the jobs for a misbehaving bot with a phabricator ticket explaining the problem and a ping on irc.

In T114384#2572962, @bd808 wrote:

Labs-announce and/or labs-l should reach all active bot developers for major announcements.

All active bot developers that host their bots on Labs, anyway.

Regarding deprecating hooks, some comments by S in https://phabricator.wikimedia.org/T54027#1124173

What if Release-Engineering-Team would have veto power for any API breaks that haven't been properly announced, both to developers via deprecation flags and to the wider communities via tech News etc?

In T114384#3283782, @Qgil wrote:

What if Release-Engineering-Team would have veto power for any API breaks that haven't been properly announced, both to developers via deprecation flags and to the wider communities via tech News etc?

Everyone with CR+-2 on Gerrit already has veto power for pretty much anything (certainly for enforcing formally accepted policies). So what you are saying really amounts to "what if RelEng would be on the hook for reviewing all API changes and verifying whether breaking ones have been properly announced" :)

In T114384#3284192, @Tgr wrote:

So what you are saying really amounts to "what if RelEng would be on the hook for reviewing all API changes and verifying whether breaking ones have been properly announced" :)

I pass :)

In this case the correct solution (as I understand it) would be for the relevant 'product owner' (in scare quotes) or roadmap owner is responsible for this. Like the newly formed MW Platform team for MW code deprecations. We (RelEng) aren't experts in the various software products that are released.

We're more than happy to consult on the actual standardized procedure, of course :)

Like the newly formed MW Platform team for MW code deprecations.

I'm not sure that putting MW Platform on the hook for reviewing all changes in core for changes is too much better than putting any other team on the hook for it. There's a difference between "these are people you should have review your change" and "these are people who get blamed for not watching every change anyone else submits and merges". The latter seems unnecessary to me.

Yeah. My initial reaction was "find the right team to be responsible" because I was thinking of the old adage "if everyone is responsible for something no one is." But maybe we can treat any standardized deprecation procedure eg T146965 as we do other best practices/standards in MW Core: those with +2 need to ensure the changes they merge comply. That is an "everyone is responsible..." type situation but it's a known variant :)

Alright, I agree it is complex. This is the main scenario that I think we should be able to avoid:

1. Team X knows that a change is coming that will break things. Usually something marked as deprecated years ago that is finally being removed.
2. While the removal of the deprecated code is technically fine, the communication of this change has been missing / weak.
3. Someone (i.e. a community liaison that happens to work with that team) becomes aware of the risk of i.e. gadgets breaking and raises the problem.
4. Everybody shrugs, the train comes, the new code is deployed, and things break.

I guess a very basic version of the above would be that Technical Collaboration could ask to hold a deployment like this for a couple of weeks until it has been properly communicated. I know nobody is stopping us from making a request like this nowadays, but somehow we don't feel empowered, and we just let the train pass, hoping for the best.

Some thoughts from a dabbler in user scripts on WMF wikis...

I think @MrStradivarius hits on one of the key issues by bringing up the differing perspectives and expectations; and I think attacking the problem from that angle has the most potential for good solutions.

For example, what if we actively change the expectations of MW developers? What if MW developers are expected to be responsible for changing all user scripts and gadget before making a known breaking change? They cannot literally do it themselves of course, but they could be responsible for making sure the needed changes happen through an established community process for technically minded volunteers. If there is a good central backlog listing the planned breaking changes accompanied by analysis of what needs fixing (which scripts call a deprecated API method, say), some guidance on how to fix it, and developer support when community volunteers get in over their head. Most technically minded community members I know of (those working on scripts and bots, say) are perfectly happy to help in this way.

And, crucially, it would turn this problem into something "developers" and "community" are working together to solve, rather than "the developers" breaking stuff and the community having to clean up the mess (or, as I imagine it looks to the developers: the community writing messy code that makes it hard for developers to move the platform forward).

Another good angle of attack is prevention: manage API usage by actively channeling scripts and gadgets toward those bits of API you are prepared to support and evolve long term. That means documenting the hell out of the APIs, giving guidance on which APIs to use for what, and giving far more weight than has previously been the case to meeting the needs of user scripts and gadgets. For example, from all available evidence OOUI is primarily a PHP framework that happens to have a JS component (and the docs definitely reflect that), and is powerful and flexible. Meanwhile user scripts and gadgets have no use for or access to PHP, and they need a simple set of UI widgets. I recently tried using OOUI to pop up a dialog box with a text field and Ok/Cancel buttons and instead of the two lines of jQuery UI code I spent days mired in figuring out a window manager(!) and subclassing a complex and mostly undocumented set of JS "mixins". After wasting a week on that I went back and did it in jQuery UI and I will scream loudly (and curse all developers) if you ever try to actually remove jQuery UI (yes, I know upstream is effectively dead). And don't get me started on finding any kind of documentation on the API that is the HTML markup structure and CSS classes of mediawiki's rendered pages: for user script and gadget developers this is often their bread and butter. Start treating this as a first class API (with docs, stability guarantees, etc.) and you'll make my life a whole lot easier.

If the various APIs (and I'm not using that term narrowly) better serve the needs of the community toolsmiths, more effort is put into helping those tools into using the maintainable paths, and deprecations is something developers and the community work on together, then a lot is solved.

Note that I'm here deliberately ignoring both PHP and schema changes. I consider those to be so in-core that that's essentially an internal problem. If you're allowing outside access to your DB schema then you have effectively turned it into an API and need to maintain it as such: and every time that hurts is a reminder that that's why we build higher level APIs that abstract that away and isn't as costly to maintain and keep stable. MW Extensions sit as a hybrid somewhere inbetween there, but I know too little about them and MW architecture to have anything intelligent to say about them (the coupling looks like a tight rather than loose one, and that (anti)pattern has known problems). I am also assuming a WMF context: managing third-party installations is a whole `nother story.

In T114384#5285151, @Xover wrote:

If there is a good central backlog listing the planned breaking changes accompanied by analysis of what needs fixing (which scripts call a deprecated API method, say), some guidance on how to fix it, and developer support when community volunteers get in over their head. Most technically minded community members I know of (those working on scripts and bots, say) are perfectly happy to help in this way.

That's mostly how JS changes happen today, except there isn't really a good way to tell which scripts need fixing (T217142: [Proposal] Use the Kafka-Logstash logging infrastructure to log client-side errors will be a step towards fixing that).

For example, from all available evidence OOUI is primarily a PHP framework that happens to have a JS component (and the docs definitely reflect that), and is powerful and flexible.

OOUI is actually a primarily JS framework, with some subset of the functionality being available in PHP-generated forms as well. Neither side is well-documented. T156235: Provide an alternative (more declarative) way to create classes in OOUI is one way of fixing that (not on anyone's roadmap currently, though).

And don't get me started on finding any kind of documentation on the API that is the HTML markup structure and CSS classes of mediawiki's rendered pages: for user script and gadget developers this is often their bread and butter. Start treating this as a first class API (with docs, stability guarantees, etc.) and you'll make my life a whole lot easier.

Currently that is blocked on having two different parsers. The new parser does have a DOM spec; switching over to it will probably take about two years.

In case you're not already aware, I'm the primary maintainer of the Action API, i.e. api.php. Also, as a volunteer contributor, I run AnomieBOT on the English Wikipedia. I'm replying mainly from those perspectives. I don't know very much about JavaScript libraries loaded in MediaWiki for use by user scripts or about class names and DOM structure in the HTML.

In T114384#5285152, @Xover wrote:

What if MW developers are expected to be responsible for changing all user scripts and gadget before making a known breaking change? They cannot literally do it themselves of course,

Exactly. Even finding the user scripts and gadgets can be problematic. The best I can do sometimes is look at which users are hitting something at a significant rate then try to look through the scripts those users are using.

but they could be responsible for making sure the needed changes happen through an established community process for technically minded volunteers. If there is a good central backlog listing the planned breaking changes accompanied by analysis of what needs fixing (which scripts call a deprecated API method, say), some guidance on how to fix it, and developer support when community volunteers get in over their head. Most technically minded community members I know of (those working on scripts and bots, say) are perfectly happy to help in this way.

Deprecations are typically announced on the mediawiki-api-announce mailing list. If people would subscribe to that and fix uses of announced deprecations, that would be very helpful.

Another thing people could do would be to pay attention to warnings returned by the API. You can do that directly when receiving the responses, or indirectly by setting a useful user agent and using Special:ApiFeatureUsage to check what has been logged for that agent.

For that matter, if people would just set a useful user agent that would at least make it easier for me to find which scripts are hitting something when I go looking at the logs.

A list of which scripts are hitting deprecated API methods is already pretty doable from a technical standpoint (although the top hitters would unfortunately include useless names like "", "Mozilla/5.0 (Blah blah) (Blah)", and "Java/1.8.0_73"), but from a privacy standpoint it would probably require that scripts specify something like a user agent under which their uses would be reported, that would also serve to explicitly opt the script in to the reporting.

Another good angle of attack is prevention: manage API usage by actively channeling scripts and gadgets toward those bits of API you are prepared to support and evolve long term.

The problem there is "evolve": it does little good to push people towards an API if they're going to write code once and never update it when the API changes.

That means documenting the hell out of the APIs,

FYI, most of the documentation of the kind you seem to be asking for[1] should really be on mediawiki.org. Which is a wiki, and anyone is welcome to work on better organizing and improving the documentation there.

If someone is willing to do the writing, I for one would be happy to answer questions about things I know about to inform that writing.

[1]: e.g. OOUI is fairly well documented at an interface level at https://doc.wikimedia.org/oojs-ui/master/js/, but that lacks higher-level information about how all the pieces fit together to do something like show a popup window.

If you're allowing outside access to your DB schema then you have effectively turned it into an API and need to maintain it as such:

Not necessarily. Toolforge provides access to cleaned-up replicas of the databases, but it comes with the caveat that people using it need to be responsive to announced changes or their things will break. And that the timeline between announcement and breakage is likely enough going to be a small number of weeks.

and every time that hurts is a reminder that that's why we build higher level APIs that abstract that away and isn't as costly to maintain and keep stable.

You seem to be assuming that developing and maintaining higher level APIs for everything people want to do on Toolforge wouldn't be costly. It's probably fairly comparable to the cost of paying people to write and edit an encyclopedia ;)

I created https://www.mediawiki.org/wiki/Template:Deprecation_policies for easier navigation between the easier policies. I seem to recall ResourceLoader modules also having a semi-official policy, but I couldn't find it.

Resubscribing so I won't forget to check what the current standards are.
Also FYI @VirginiaPoundstone and @daniel .