Hi all! Per yesterday's TechCom meeting, the last call ended without any concerns being raised. If you work on extensions or MediaWiki core, please read through the changes outlined below, and have a look at the policy page at <https://www.mediawiki.org/wiki/Stable_interface_policy>.
Thanks! Am 28.02.20 um 11:38 schrieb Daniel Kinzler: > 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
