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@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l