Create Task
Maniphest T115341

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

Description

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

Related Objects
Search...

MrStradivarius created this task.Oct 13 2015, 3:45 PM
MrStradivarius updated the task description. (Show Details)
MrStradivarius raised the priority of this task from to Normal.
MrStradivarius claimed this task.
MrStradivarius added projects: User-notice, Community-Tech, Developer-Advocacy, MediaWiki-API.
MrStradivarius added a subscriber: MrStradivarius.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 13 2015, 3:45 PM
Anomie moved this task from Unsorted to Non-Code on the MediaWiki-API board.Oct 13 2015, 5:59 PM
Anomie added a subscriber: Anomie.
This comment was removed by Anomie.
Liuxinyu970226 set Security to None.Nov 15 2015, 1:04 AM
Liuxinyu970226 added a subscriber: Liuxinyu970226.
Krinkle added a subscriber: Krinkle.Dec 8 2015, 7:40 PM
kaldari added a subscriber: kaldari.Dec 11 2015, 6:54 PM

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

DStrine removed a project: Team-Practices.Jan 20 2016, 7:23 PM
DStrine added a subscriber: DStrine.

TPG has removed our project. We reviewed this several times. This seems more related to Developer-Advocacy

Qgil added a comment.Jan 21 2016, 11:38 AM

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.

• RobLa-WMF moved this task from Inbox to External on the Architecture board.Mar 17 2016, 10:40 PM
Krinkle added a comment.EditedMar 24 2016, 2:19 AM

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 irc.wikimedia.org). 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 www.mediawiki.org. 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:

Qgil added a comment.Oct 27 2016, 1:33 PM

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: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/Call_for_participation

Content licensed under Creative Commons Attribution-ShareAlike 3.0 (CC-BY-SA) unless otherwise noted; code licensed under GNU General Public License (GPL) or other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL