On several occasions, I struggled to explain the stability interface policy approved in T193613. I noticed at times that a point I made wasn'tt easily linkable on the page. My interpretation wasn't contradictory per se, but it also wasn't obvious that what I said is how it was meant to be intepreted. There are areas that contain gaps or are split between sections. I'd like to be able to quickly find (or link to) what the policy is for a given scenario, and what one's options would be.
I started drafting an overhaul of that page in which I simplify the language, make the structure easier to digest for wide ranger of audiences (core dev, extension dev, contributor, code reviewer, etc.). I also accomodated the new hooks system per T240307 with some pointers.
I considered publishing this as non-nominal change, but alas, I found some inconsistencies and blank spots I was unable to write clearly without being a nominal change – hence this RFC.
- Resolve ambiguity over what to do with classes that are stable to construct ("stable to call", 'stable to instantiate", "newable").
- The policy describes "stable to instantiatie" as as being distinct from "stable to call". However later descriptions of "stable to call" also cover constructor methods. It is not obvious what the requirement annotation(s) are or where they should be put.
- Explain why stable constructors are discouraged.
- The policy mentions "dependency injection", but given we do allow stable constructors in some cases I think we should explain in a sentence or two why an author would want want to avoid it.
- Resolve contradiction about whether abstract methods of an extendable class are considered stable to override without the need for an annotation.
- The policy says "stable for overriding: … This annotation should be applied to all abstract methods of classes marked as stable for subclassing". But, it also says "Only methods explicitly marked this way (or declared abstract) are safe to override".
- Explain why interfaces are discouraged.
- The policy mentions "abstract base classes", but does not explicitly state what problems this avoids or solves.
- Define what expectations are put on the author (e.g. MW core) for methods that are "stable to override".
- Document the status quo that hard deprecation may not happen until WMF production no longer uses the code path in question, or decide otherwise.
- Section "Stable to call" now includes constructor methods with @stable to call. It now explains the ceveat with a stable constructor in relation to dependency injection. The @newable annotation is explained as optional marking for the class block.
- Section "Stable to override" now includes "Methods that are declared as abstract".
- Section "Stable to extend" now explains the caveat with interfaces as extension points in its recommendation for base classes.
- Section "Stable to override" now defines a contract between core and class method overrides. The signature won't break, the method will continue to exist, and it will continue to get called.
- Section "Deprecation" now includes "Wikimedia production" in addition to non-deprecated MW configuration and bundled extensions/skins in its list of areas that must be updated before hard-deprecation may occur.
- Detailed changelog at: https://www.mediawiki.org/wiki/User:Krinkle/Stable_interface_policy/Changes.