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