Product Manager, MediaWiki Platform
---------- Forwarded message ---------
From: Daniel Kinzler <dkinzler(a)wikimedia.org>
Date: Fri, Feb 28, 2020 at 6:01 AM
Subject: [Wikitech-l] Last Call: Updated Stable Interface Policy /
To: Wikimedia developers <wikitech-l(a)lists.wikimedia.org>
TL;DR: A new policy defining stable interfaces for use by extensions, and
deprecation process that must be followed when changing such stable
is now in the Last Call period. If no concerns remain unaddressed by March
the new policy will be adopted as official policy. The policy will apply to
MediaWiki 1.35 and later.
The new policy is designed to better protect extensions from breakage when
things change in core, by being more restrictive about what extensions can
Draft document: https://www.mediawiki.org/wiki/Stable_interface_policy
RFC ticket: https://phabricator.wikimedia.org/T193613
Please comment there. Read below for a summary of changes.
TechCom has been working on a Stable Interface Policy for MediaWiki's PHP
for a while. Previously, the definition of the stable interface that can
used by extensions was part of the Deprecation Policy. The new policy
much more detailed and explicit about what extensions can expect to remain
stable and follow the deprecation process, and which things can change
The introduction of the new policy is driven by problems we found while
to refactor core code with the aim to reduce coupling. For instance, when
following the Dependency Injection pattern, the constructor of service
is technically public, but is not stable for use outside the module.
The solution is to be more explicit about different kinds of stability (e.g.
whether a method is stable for callers, or can also be safely overwritten).
To allow us more freedom to restructure the source code, the new policy is
restrictive with respect to what extensions can expect to be able to do
(e.g. subclass core classes). This is balanced by improved guarantees in
previously unspecified cases (e.g. stability of protected methods).
The new policy specifies different kinds of stability, establishes defaults
different parts of the code, and defines new annotations to be used in the
documentation. Once the policy has been adopted, these annotations are soon
be added to the code.
This will hopefully allow us to more quickly improve the structure and
of core code, and reduce the risk of breaking extensions in the future.
Summary of the new policy:
For extension authors:
* It's generally safe to call public methods, and to access public fields in
classes defined by MediaWiki core, unless these methods are documented to be
unsafe (e.g. annotated as @deprecated, @unstable, or @internal).
* It's generally unsafe to extend (subclass) classes or implement interfaces
defined by MediaWiki core, unless that class or interface was marked as
for subclassing or @stable for implementation, respectively. In particular,
constructor signature may change without notice, and abstract methods may be
added to interfaces.
* It's generally unsafe to directly instantiate (using new) classes defined
MediaWiki core, unless that class is marked as @newable.
* It's generally unsafe to rely on global variables from MediaWiki core. Use
methods such as MediaWikiServices::getInstance() or
When changing existing code:
* Keep public methods and hook signatures backwards compatible for callers.
Follow the deprecation process when removing them.
* Keep constructor signatures backwards compatible if the constructor was
@stable for calling.
* Ensure compatibility of method signatures for code that overrides them if
are marked @stable for overriding.
* Do not add abstract methods to classes or interfaces marked as @stable for
subclassing or @stable for implementation.
When defining extension points:
* When defining hooks, keep the signature minimal, and expose narrow
ideally only pure value objects.
* When defining an interface to be implemented by extensions, provide a base
class, and mark it as @stable for subclassing.
* Discourage extensions from directly implementing interfaces by marking
@unstable for implementation. If direct implementation is to be allowed,
the interface @stable for implementation.
Notable changes from the 1.34 policy:
* Public methods are per default considered stable only for calling, not for
* Constructors are considered unstable per default.
* Classes and interfaces are considered unstable for subclassing and
implementation, unless documented otherwise.
* Code not used in a public repository that is part of the Wikimedia
may be changed or removed without deprecation.
Principal Software Engineer, Core Platform
Wikitech-l mailing list
The following meeting has been modified:
Subject: Monthly #mwstake meeting
Organizer: "#mwstake Calendar" <calendar(a)mwstake.org>
Time: 11:30:00 AM - 12:30:00 PM GMT -05:00 US/Canada Eastern [MODIFIED]
Recurrence : The first Friday of every 1 month(s). No end date. Effective Mar 6, 2020
Required: mediawiki-enterprise(a)lists.wikimedia.org; yoakam(a)lanl.gov; evita.hollis(a)ge.com; ttenbergen(a)gmail.com; ccicalese(a)wikimedia.org; gtisza(a)wikimedia.org; gtisza(a)gmail.com; bryandamon(a)gmail.com; nancy.gertrudiz(a)gmail.com; lex(a)dataspects.com; ad(a)wikibase.nl ...
Please join us for the monthly #mwstake meeting this Friday.
[ https://meet.google.com/mdd-ufhn-ksb | https://meet.google.com/mdd-ufhn-ksb ]
See [ https://mwstake.org/mwstake/wiki/Main_Page | mwstake.org ] for time and details.
Registration is open for EMWCon 2020 , the Enterprise MediaWiki
You must register by March 2nd to be able to attend the tour of NASA's Plum
Brook Station  and other pre-planned conference events.
Talks are still being accepted . Please help us design a well-planned
program by submitting your talk proposals as soon as possible but no later
than March 16.
The conference will be held on April 1-3 in Sandusky, Ohio (50 miles west
of Cleveland). EMWCon is a three-day conference featuring discussions of
topics related to "Enterprise MediaWiki", i.e. the usage of MediaWiki
software by and within companies, non-profits, governments, and other
organizations. The intended audience of EMWCon Spring 2020 is anyone who
uses, or would like to learn to more about, MediaWiki. This year the
conference will be preceded by an optional, informal two day hackathon on
March 30 and 31. The conference venue is located across the street from
NASA's Plum Brook Station, where NASA Orion Spacecraft is presently being
tested for the Artemis-1 mission to the moon.
The EMWCon 2020 organizing committee
* Richard Evans (General Chair)
* Yaron Koren (Registration Chair and Principal Sponsor)
* Cindy Cicalese (Program Chair)