### Motivation
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.
### Requirements
(WARNING)
Current policy as of November 2020: <https://www.mediawiki.org/w/index.php?title=Stable_interface_policy&oldid=4214637&diff=4242323&diffmode=source>
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.
### Exploration
(NOTE)
Draft: **<https://www.mediawiki.org/wiki/User:DKinzler_(WMF)/Stable_interface_policy>**.
(NOTE)
Diff, per November 23: **<https://www.mediawiki.org/w/index.php?title=Stable_interface_policy&type=revision&diff=4246844&oldid=4208867&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.
* Define a recommended timeline for the deprecation process: ideally, hard deprecation follows soft deprecation within the same release, and removal follows after one release.
* Clarify that the deprecation period may be skipped only if it appears that the code was never used elsewhere. Previously, the policy stated that deprecation can be skipped if the code is not currently used within the ecosystem, which would imply that it is sufficient to remove known usages immediately before removal, without consideration of usages outside the known ecosystem.
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.
### Resourcing and Stewardship
No work beyond writing the draft is needed. Stewardship of the policy remains as before.
### See also
* {T268328}