Page MenuHomePhabricator

Are traits part of the stable interface?
Open, Needs TriagePublic

Description

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

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald Transcript

Not sure if this requires a full RfC or if I wrote this correctly, but tagging TechCom-RFC to be on the safe side.

Training as question for the committee. Might not need it's own RFC if it's only a clarifying question based on wording.

Thanks for bringing this up! I'm working on an update to the stable interface policy. I added a section on traits: https://www.mediawiki.org/wiki/User:DKinzler_(WMF)/Stable_interface_policy

Interestingly, in traits, private methods are part of the public interface.