Re: [Wikitech-l] Last Call: Updated Stable Interface Policy / Deprecation Policy

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