The proposed amendment of the Stable Interface Policy aims to do the following:
* remove ambiguity and clarify wording
* provide guidance for cases previously not covered
* streamline the deprecation process to allow for deprecated code to be removed more quickly
* clarify responsibilities during the deprecation period to provide more clarity and better support for third party extension authors.
Current policy as of November 2020: <https://www.mediawiki.org/w/index.php?title=Stable_interface_policy&oldid=4242722>
1. Define guarantees and annotations for PHP ''traits''. This was previously missing.
1. Define guarantees and a deprecation process for member fields. This was previously missing.
1. Define a process for deprecating methods that are stable to override. This was lacking a mechanism for triggering deprecation warnings when the method is overridden.
1. Define which extensions are to be considered to what extent when deciding whether code can be hard-deprecated or removed.
1. Define who is responsible for removing usages of deprecated code.
Diff, per December 2: **<https://www.mediawiki.org/w/index.php?title=User:DKinzler_(WMF)/Stable_interface_policy&type=revision&diff=4258989&oldid=4242722&diffmode=source>**
Notable changes to the stable interface definition:
* Provide a definition of "MediaWiki ecosystem" (see also T268328) and "Wikimedia maintained code".
* Declare that traits are not safe to use unless marked as `@stable to use`. In traits that are safe to use, all methods, including private methods, are //stable to call//.
* Declare that fields are safe to read, but not safe to write. Define a process for deprecating fields.
* Consider the use of interfaces in the new hook system.
* State that when deprecating methods that are stable to override, if the method is overridden by a subclass, a deprecation warning must be triggered, but the method must still be called. (helper code for this is pending, see T267080)
Notable changes to the deprecation process:
* Clarify that the goal of the deprecation process is to remove deprecated code as soon as possible without breaking things in critical ways.
* Define a hierarchy of support for different groups of extensions: those used and maintained by WMF have the highest priority, popular open source 3rd party extensions should receive active support, other 3rd party extensions should receive reasonable warning about changes.
* Clarify that individuals or teams that deprecate code are also responsible for following up and removing usages of that code, and support authors of affected extensions.
* Clarify the timeline for the deprecation process:
** ideally, hard deprecation follows soft deprecation within the same release
** removal may occur after hard deprecation in at least one release and at least three months on the development branch.
* Remove the section defining exceptions allowing removal without deprecation. Instead:
** Allow hard deprecation by public announcement in cases where it is not possible to emit deprecation warnings.
** Allow removal of code that was //never// used elsewhere, or never released.
* Clarify that deprecation and removal should not be backported to release candidates, and should ideally be performed soon after a release, rather than shortly before a release.
Notable changes to the scope:
* Extensions are no longer expected to provide any stable interface per default - the scope had been extended to cover extensions in March (T193613), which now seems like a mistake: MediaWiki is designed as an extensible framework, but most extensions are not.
* The MediaWiki "ecosystem" is defined to include actively maintained extensions hosted by Wikimedia and extensions listed by the MediaWiki Stakeholder Group.
### Resourcing and Stewardship
No work beyond writing the draft is needed. Stewardship of the policy remains as before.
### See also