Background
The current policy at https://www.mediawiki.org/wiki/Stable_interface_policy does not mention traits, nor do I see them mentioned at T255803: RFC: Amendment to the Stable interface policy, June 2020.
Since traits may define abstract methods that must be implemented by classes that use them, and since it is generally not safe to extend core classes or implement core interfaces, I would assume that the default would be that traits are not a part of the stable interface.
If, indeed, they are by default not part of the stable interface, how should traits that are stable for extensions to use be documented? Currently:
- the SearchResultSetTrait trait has, in its documentation block, This trait can be used directly by extensions providing a SearchEngine.
- the HTMLFormElement trait has, in its documentation block, @stable to extend
Proposal
I propose that traits be, by default, unstable to use in extensions. To mark a trait as stable for use, a new annotation is added, @stable to use
For traits that are stable for use, by default, they are not stable to extend/override, unless the relevant tag (@stable to extend / @stable to override) is present.
Impact
A quick codesearch revealed that a number of core traits not documented as stable for using are used in a number of extensions. Not an exhaustive list:
- FactoryArgTestTrait -> Math
- HandlerTestTrait -> IPInfo
- MediaWikiCoversValidator -> Wikibase, Scribunto, EventBus, Collection, TextExtracts
- SearchResultTrait -> CirrusSearch
- SearchResultSetTrait -> CirrusSearch
- ApiWatchlistTrait -> FlaggedRevs
- ApiBlockInfoTrait -> RegexBlock, VisualEditor