Page MenuHomePhabricator

Create a standard timetable for deprecating public-facing code across all WMF projects
Open, MediumPublic


At the moment, removal of code can take developers of community tools by surprise, despite the length of time the code is typically marked as deprecated for. This is partly because procedures for deprecating public-facing code are fragmented - the way code is deprecated in the Action API is different from the way it is deprecated in the JavaScript API, which in turn is different from the way breaking changes are made to the WMF site configuration, etc.

It is also partly because the traditional methods of reaching out to tool maintainers - such as wikitech-l, wikitech-ambassadors and Tech News - aren't as effective as they could be. There are a significant number of tools whose maintainers don't pay attention to these sources, and there are a significant number of tools that have no maintainer but are still in active use, which must be updated by other community members.

To fix this, I propose that we create a standard timetable for deprecating code across all areas of MediaWiki and the Wikimedia wikis, with standard procedures for notifying the community at regular intervals before breaking changes are made.

An example timetable could look something like this:

  • 6 months before removal, mark the code as deprecated in the console and determine which scripts need to be updated. Notify community noticeboards on affected wikis, and leave a note on talk pages of affected gadgets and on the user talk pages of their maintainers.
  • 1 month before removal, determine the remaining scripts that need to be updated, and leave a message on the community noticeboards of the remaining wikis, as well as on the talk pages of the remaining gadgets and the user talk pages of their maintainers.
  • Do the same thing 1 week before removal, and 1 day before removal.
  • After removal, leave a final notification.

Doing all of this manually would be a lot of work, so wherever possible this process should be automated. We will also need to have a mechanism for users to opt out if they don't want to receive notifications, and it would also be a good idea to create guidelines for notifications so that they are as useful as possible, e.g. every notification should have a link to a clear explanation of how to update the deprecated code.

See Also:
T114384: Standardise procedures for deprecating public-facing code
T149727: Deprecated MediaWiki extension API functions should be moved to a compatibility library instead of being dropped entirely
T146965: RFC: Deprecation policy for PHP code in MediaWiki
T115341: Create a standard timetable for deprecating public-facing code across all WMF projects

Event Timeline

MrStradivarius claimed this task.
MrStradivarius raised the priority of this task from to Medium.
MrStradivarius updated the task description. (Show Details)
MrStradivarius subscribed.
Anomie subscribed.
This comment was removed by Anomie.

Sounds like this should be an RfC rather than a Phabricator task.

DStrine subscribed.

TPG has removed our project. We reviewed this several times. This seems more related to #devrel

Well, not at all. Developer-Advocacy works with community and third party developers. We are not the ones maintaining the code or creating policies for its maintenance.

I'm not sure a universal one-fits-all policy can or should exist for all deprecations. At least the length of time may vary depending on what is being deprecated (a random public function in MediaWiki PHP vs. a public service such as And parties that should be communicated with may also vary. This must be handled on a case-by-case basis. For example, it may require input from relevant product managers or operations personnel.

However, I agree we should formalise the general process. This task is in my opinion quite suitable as ArchCom-RFC. The outcome of it would be a document detailing our practices on A few things come to mind that we could document (and enforce):

  • Not removing public methods without it being deprecated for at least 1 major release.
  • Mentioning all deprecations and removals in the release notes.
  • Announcing the deprecation and removal of a "major" feature on Wikitech-l (e.g. Sajax library, IE7 support etc.).
  • Announcing the deprecation and removal of a "major" client-side feature on Tech-News (posted on-wiki and on wikitech-ambassadors) and Wikitech-l.

More details about these and additional things we, as a community, think should or should not be required steps; can be discussed on this task and (eventually) in one or more RFC office hours on IRC.

Third-party policies:

Would this task be a good topic for the Wikimedia-Developer-Summit (2017) ? If so, the deadline to submit new proposals is next Monday, October 31:

This task has been assigned to the same task owner for more than two years. Resetting task assignee due to inactivity, to decrease task cookie-licking and to get a slightly more realistic overview of plans. Please feel free to assign this task to yourself again if you still realistically work or plan to work on this task - it would be welcome!

For tips how to manage individual work in Phabricator (noisy notifications, lists of task, etc.), see for available options.
(For the records, two emails were sent to assignee addresses before resetting assignees. See T228575 for more info and for potential feedback. Thanks!)