It's about time we thought about how we deprecate public-facing APIs used by gadgets, bots, Scribunto, and others. Our current procedures can sometimes take community tool developers by surprise, despite the length of time that code is typically marked as deprecated for. By creating a standard procedure for community outreach when deprecating code, we can increase the number of tools that get updated in a timely manner and prevent disruption for the editors that use them.
= Expectations =
In my experience, expectations from communities regarding deprecated code are quite different from those from MediaWiki developers. The community attitude can be summed up as:
# If you break it, you fix it.
# If you want to get my attention, leave me a message on my talk page.
# If you want to let the wider community know about something, post it on the relevant noticeboard.
The MediaWiki developer expectations, however, go something like this:
# You are responsible for fixing code you maintain. We will be nice and give you lots of time before removing deprecated code from MediaWiki.
# If you want to let tool developers know about deprecated code, show them a warning in the console.
# If you want to notify the community about something, use wikitech-l, wikitech-ambassadors and/or Tech News.
There are problems with a number of these expectations. For example, a significant number of gadgets on WMF wikis don't have an active maintainer, and even if gadgets/bots have an active maintainer, not all of them will notice warnings in the console. Also, most maintainers aren't subscribed to wikitech-l or wikitech-ambassadors, and by the time impending removals of deprecated code reach the mailing lists and Tech News, it may be too late to fix tools in time. This is particularly true for tools that are still in active use but don't have an active maintainer, as they must be updated by other technically-minded users in the community.
From the community side, it isn't practical to expect MediaWiki developers to update all tools using deprecated code. There are hundreds (thousands?) of gadgets on WMF wikis now that use deprecated code, and updating them all may take a prohibitive amount of time, depending on what needs updating and how many scripts are affected. Leaving messages on the talk pages of all users using deprecated code can also be very time-consuming. We need to think about how we can get community tools updated in a way that doesn't use excessive developer time.
= Closing the gap =
There are several things we can do to bring communities' and developers' expectations closer in line with each other.
* T115341 Set a specific timetable for notifying communities about removal of deprecated code. For example, you could send notifications 6 months before removal, then 1 month before, then 1 week before, then 1 day before, then after removal.
* Create infrastructure for tracking deprecated code so that technically-minded users can work on the backlog with lots of time to spare.
* T35355 Create infrastructure for tracking how widely used gadgets are, so that the important ones can be fixed first, and the ones that don't matter can be left alone.
* Create infrastructure for notifying the probable maintainers of gadgets on their talk pages.
* Prohibit the removal of code if it is used in a gadget that is used by, say, more than 100 active users. Make it the responsibility of WMF Community Tech to update such gadgets.
* Move very highly used gadgets to MediaWiki extensions. Good candidates for this would be Popups, HotCat, and Contribsrange.
On a longer-term basis, we could also think about extending this infrastructure to deprecate features of wikitext. This kind of backlog-tracking and community outreach would be key to finally fixing T14974. It would also be useful for replacing uses of the Timeline extension with something based on the new Graph extension.
= Expected outcome ==
At the Developer Summit, we should decide whether we want to implement a procedure like this, and if so, what the main points of it should be. We should also decide which of the technical aspects we are willing/able to implement, and commit to a rough timetable for them. The fine details of the procedure can be worked out as part of a community consultation after the summit.
= Relevant links =
* [[ https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap | Requests for comment/API roadmap ]] - contains guidelines for deprecating API features
* [REST API versioning policy](https://www.mediawiki.org/wiki/API_versioning) sets deprecation & versioning policies for the REST API.
* [[ https://meta.wikimedia.org/wiki/Tech/Ambassadors | Tech Ambassadors ]]
* [[ https://outreach.wikimedia.org/wiki/Best_practices_for_reaching_out_to_projects_in_multiple_languages | Best practices for reaching out to projects in multiple languages ]]
* Discussion about removing the deprecated Sajax libarary: T55120
* Deprecation of pre-ResourceLoader loading of gadgets catching enwiki editors by surprise: [[ https://en.wikipedia.org/wiki/Wikipedia:Village_pump_%28technical%29/Archive_139#Legacy_gadgets_are_disabled | here]] and [[ https://en.wikipedia.org/wiki/Wikipedia_talk:Tools/Navigation_popups#Anyone_else_getting_recent_breakage.3F | here ]]