Cross posting.
______________________________
Cindy Cicalese
Product Manager, MediaWiki Platform
Wikimedia Foundation
---------- 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 /
Deprecation Policy
To: Wikimedia developers <wikitech-l(a)lists.wikimedia.org>
Hi all!
TL;DR: A new policy defining stable interfaces for use by extensions, and
the
deprecation process that must be followed when changing such stable
interfaces,
is now in the Last Call period. If no concerns remain unaddressed by March
11,
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
safely do.
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.
Long version:
TechCom has been working on a Stable Interface Policy for MediaWiki's PHP
code
for a while[1]. Previously, the definition of the stable interface that can
be
used by extensions was part of the Deprecation Policy[2]. The new policy[3]
is
much more detailed and explicit about what extensions can expect to remain
stable and follow the deprecation process, and which things can change
without
notice.
The introduction of the new policy is driven by problems we found while
trying
to refactor core code with the aim to reduce coupling. For instance, when
following the Dependency Injection pattern, the constructor of service
classes
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
more
restrictive with respect to what extensions can expect to be able to do
safely
(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
for
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
to
be added to the code.
This will hopefully allow us to more quickly improve the structure and
quality
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
@stable
for subclassing or @stable for implementation, respectively. In particular,
the
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
by
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
MediaWikiServices::getMainConfig() instead.
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
marked
@stable for calling.
* Ensure compatibility of method signatures for code that overrides them if
they
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
interfaces,
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
them as
@unstable for implementation. If direct implementation is to be allowed,
mark
the interface @stable for implementation.
Notable changes from the 1.34 policy:
* Public methods are per default considered stable only for calling, not for
overriding.
* 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
ecosystem
may be changed or removed without deprecation.
[1] https://phabricator.wikimedia.org/T193613
[2] https://www.mediawiki.org/wiki/Deprecation_policy
[3] https://www.mediawiki.org/wiki/Stable_interface_policy
--
Daniel Kinzler
Principal Software Engineer, Core Platform
Wikimedia Foundation
_______________________________________________
Wikitech-l mailing list
Wikitech-l(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 ...
Optional: mah(a)nichework.com
*~*~*~*~*~*~*~*~*~*
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 [0], the Enterprise MediaWiki
Conference!
You must register by March 2nd to be able to attend the tour of NASA's Plum
Brook Station [1] and other pre-planned conference events.
Talks are still being accepted [2]. 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.
Sincerely,
The EMWCon 2020 organizing committee
* Richard Evans (General Chair)
* Yaron Koren (Registration Chair and Principal Sponsor)
* Cindy Cicalese (Program Chair)
[0] https://www.mediawiki.org/wiki/EMWCon_Spring_2020
[1]
https://en.wikipedia.org/wiki/Glenn_Research_Center#Plum_Brook_Field_Station
[2] https://www.mediawiki.org/wiki/EMWCon_Spring_2020#Talks