Page MenuHomePhabricator

RFC: Deprecation policy for PHP code in MediaWiki
Closed, ResolvedPublic



One of MediaWiki's greatest strengths is the diverse extension ecosystem. But we (MediaWiki core developers) can often make it hard for extension developers to keep up with constant breaking changes. We do not have a standard deprecation policy, leading to widely inconsistent practices depending on who writes and/or reviews the patch. Some reviewers expect you to fix all instances in Gerrit before merging a core deprecation patch, others will be fine with fixing none.

For more:

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
T115341: Create a standard timetable for deprecating public-facing code across all WMF projects

Event Timeline

That task is more about frontend code ("public-facing") while this is strictly scoped to developer-facing PHP code.

RobLa-WMF renamed this task from [RfC] Deprecation policy to [RfC] Deprecation policy for PHP code in MediaWiki.Sep 30 2016, 9:01 PM
RobLa-WMF updated the task description. (Show Details)

This RFC was approved fro final call at the IRC meeting on December 14. See the below summary. Please raise any objections until December 21. If no pertinent new issues are raised, the deprecation policy as proposed on will become official.


  • '''Deprecation policy for PHP code in MediaWiki''' (DanielK_WMDE_, 22:04:54)
    • ''LINK:'' (DanielK_WMDE_, 22:04:59)
    • ''LINK:'' (DanielK_WMDE_, 22:05:30)
    • ''LINK:'' (DanielK_WMDE_, 22:06:11)
    • <tgr> seems reasonable to me (DanielK_WMDE_, 22:28:18)
    • <Platonides> I would restrict the PHP API to which it applies to that which appeared on at least one official release (DanielK_WMDE_, 22:28:26)
    • <gwicke> I like what I see overall (DanielK_WMDE_, 22:29:07)
    • <TimStarling> I wonder if there should be an exception for removing methods that were never called by any extension (DanielK_WMDE_, 22:29:28)
    • <TimStarling> I think there's a lot of code which is extremely unlikely to have ever been called by an extension, and the only reason it's not marked @unstable is because nobody bothered or thought it was necessary (DanielK_WMDE_, 22:29:51)
    • <legoktm> moving something from public to protected should fall under this policy (DanielK_WMDE_, 22:30:37)
    • a preocedure for deprecating hooks should be mentioned explicitly (DanielK_WMDE_, 22:31:02)
    • <legoktm> TimStarling: if something is unreasonable to keep supporting and it has no callers, then I think it's fine to get rid of right away. But if it's trivial to keep around, I don't think it should be removed for the sake of removal. (DanielK_WMDE_, 22:31:32)
    • procedure for hooks: put a warning in docs/hooks.txt. Use the $deprecationVersion parameter in Hooks::run. (DanielK_WMDE_, 22:34:26)
    • to make something private, create a private doWhateverInternal() for the private usage, and have the public one emit the warning and call the internal function. (DanielK_WMDE_, 22:37:04)
    • <tgr> for fields we should just treat soft deprecation as hard, I don't think it's worth the effort and maintenance burden to try to make it emit warnings (DanielK_WMDE_, 22:39:28)
    • the policy should mention how to mark fields as deprecated, or for becoming private (DanielK_WMDE_, 22:42:16)
    • <tgr> "Some legacy code may not have any visibility modifiers, in which case it is not considered to be part of the stable interface. Developers SHOULD add visibility modifiers as soon as possible, and use judgement when making de-facto public code protected or private. New code MUST have explicit visiblity set on all properties and functions." (DanielK_WMDE_, 22:42:50)
    • ''LINK:'' (DanielK_WMDE_, 22:48:05)
    • ''LINK:'' (legoktm, 22:52:41)
    • ''LINK:'' (DanielK_WMDE_, 22:52:52)
    • <tgr> (I still think should be clarified but that's somewhat outside scope) (DanielK_WMDE_, 22:58:07)
    • legoktm's proposal for a new deprecation policy is going to final call. (DanielK_WMDE_, 22:58:29)

@daniel Can we consider the policy approved now? There have been no objections raised AFAIK. I'll take care of updating the relevant pages on mw.o if so.

@Legoktm, I am also not aware of any objections, but lets wait for @daniel to comment as well.

Yes, sorry for dropping the ball on this. I failed to send out the announcement of the approved Last Calls, as well as the regular ArchCom notes, before the holidays. I'm catching up on that now.

This final call for this RFC, as posted to wikitech-l on 2016-12-16, has passed without any new concerns being raised.

The RFC is thus approved.

The deprecation policy as described in the RFC should be considered official policy.

Approved, closing

Krinkle renamed this task from [RfC] Deprecation policy for PHP code in MediaWiki to RFC: Deprecation policy for PHP code in MediaWiki.Mar 22 2018, 1:40 AM