Page MenuHomePhabricator

Write a deprecation how-to or checklist
Open, Needs TriagePublic

Description

In cases such as https://gerrit.wikimedia.org/r/#/c/258173/1 I'd like to point the developer to a help page containing a list of things to do when filing a patch which removes a function, variable or other.

The help/howto/checklist doesn't need to pretend being comprehensive, mandatory or anything: it should simply list some (obvious?) items which a dev might want to check, like:

  • find out why the thing was deprecated or suggested for deprecation, link the commit and/or surrounding discussion;
  • ensure the reasons are still relevant and summarise them in at least one line on your commit message;
  • file patches for all remaining uses of the thing surviving in (non-archived) gerrit repositories, e.g. by using ack-grep --php on the /shared/mediawiki/ checkout in Tool Labs;
  • check what older releases of extensions and core still used the thing and mention which would be broken by your patch;
  • notify the relevant mailing lists (wikitech-l at a minimum; mediawiki-l if the thing was widely used at some point; team or individual emails for developers who are known to have used the thing widely);
  • ...