Stable interface policy/T255803 Draft/Changes

Structure:


 * Consolidate information about a kind of stability into its own section. Previously it was spread across different sections. For example, the meaning of "stable to call", what falls under it by default, how to opt-in/opt-out.
 * Provide the "quick guide" sentences with a  in each section instead. This facilitates scanning and avoids having to find your way up and down the page. A much reduced version of the guick guide still exists but it no longer tries to cover every area and every edge case.

Bbikeshedding:


 * The grammatical form of annotations changed from present continuous to active. I believe this shorter form uses words we more commonly use and maybe easier to spell and recognise, especially for non-native speakers. For example, "call", "extend", and "override" instead of "calling", "overriding", "subclassing" and "implementation".

Content changes:


 * Merge "stable to subclass" and "stable to implement". (The quick guide did this is already.)
 * Fix confusing overlap between "stable to call" and "stable to construct" (newable). Previously "stable to call" said constructors are a method, but then most of its information was not applicable to constructors (especially methods being stable by default). It whether people should use ,  or both. I've removed constructors from the "stable to call" scope and moved any relevant text about it to "Stable to construct".
 * Fix contradiction about overriding methods. It said "stable for overriding: … This annotation should be applied to all abstract methods of classes marked as stable for subclassing". But, it also said any method declared abstract is safe to override by default in "Only methods explicitly marked this way (or declared abstract) are safe to override". I leaned toward requiring the latter, which mandates fewer annotations – abstract method are stable to override by default (see Stable to override).
 * Fix contradiction about "@deprecate" instructions requirement. The "Stability annotations" section said authors SHOULD do so, but the "Deprecation" section said authors MUST do so. I leaned toward the status quo of MUST.
 * Use consistent wording for instantiation. Previously "safe to call", "stable to instantiate" and "newable". I went with "stable to construct" for now.

Content additions:


 * Explain the recommendation for extension points to use abstract classes over interfaces. This was mentioned in four different places, but never explained. Now consolidated and explained under Stable to extend.
 * Define what "stable to override" actually promises. One might naively assume it just means core can't replace the method's signature (as that would could cause a PHP error). But I believe the real intent is that "stable to override" (also) means that core must continue to call this method to let it do its thing. Removed the base method and no longer calling it, would not cause a PHP error, but should be considered breach of contract, I think? I've documented this under Stable to override.
 * Explain why using "stable to construct" is discouraged for classes other than value objects. It previously just mentioned "dependency injection". I've written down that the intent is to allow authors to add and change their dependencies without requiring deprecation (see Stable to construct).
 * Make "@unstable for implementation" a first-class citizen. It was previously omitted from all places that explains different kinds of stabilities, except for one line buried in a section about annotations. I've changed this to be phrased positively, for consistency with other guarantees, as Stable to type, and given it the same exposure as other stability kinds.