Stable interface policy/T255803 Draft/Changes

Changes since revision 3711823

Structure:


 * The definitions for different kinds of stability has been consolidated to one section per kind of stability. Previously these were spread across many different sections. For example, the meaning of "stable to call", what falls under that by default, and how to opt-in/opt-out are now documented together.
 * The page has been restructured to contextually provide "quick guide" sentences with  within each section (instead of in their own section). These can still be quickly scanned across the page, but this way the additional information is nearby without needing to mentally cross-reference.

Bbikeshedding:


 * The grammatical form of annotations changed from present continuous to active. For example, " " instead of " ". I believe this involves a more common form for the words we use, and is often the same word the related noun. These may also be easier to remember and spell, especially for non-native speakers.

Content changes:


 * The "stable to subclass" and "stable to implement" concepts were merged, as "stable to extend".
 * The "stable to call" and "stable to construct" sections had a lot of overlap. This was confusing to me because most of "Stable to call" was not applicable to constructors (especially the bit about public methods being stable by default). It was also unclear whether the  or   annotation should be used on constructors. Given there was already a separate section about instantiation, I've moved the relevant information there. See "Stable to construct".
 * There were three different descriptions for constructors: "safe to call", "stable to instantiate" and "newable". There were also two competing annotations described:  and  . For consistency it now uses only one description (I went with "stable to construct"), and one annotation.
 * There was a contradiction about overriding methods. It said "stable for overriding: … This annotations should be applied to all abstract methods of classes marked as stable for subclassing". But, it also said that 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 fewer annotations – thus considering an abstract method stable to override by default. See Stable to override.
 * There was a contradiction about the requirement to include instructions in a @deprecate annotation. The new "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.

Content additions:


 * The recommendation for extension points to use abstract classes over interfaces was not explained, and only described in very few words (in four different places). An explanation was added, and the descriptions consolidated under Stable to extend.
 * The meaning of "stable to override" was unclear. For example, if the base class keeps the signature unchanged (or simply removes the base method) and no longer calls it anywhere, it would not cause any PHP warnings. I assume the contract for an override is about how and when it is called. This is now written down. See Stable to override.
 * It was unclear why "stable to construct" was discouraged for classes other than value objects. It mentioned "dependency injection". I assume the intent is to allow authors to add and change their dependencies without requiring deprecation. This is now written down under Stable to construct.
 * The idea for "@unstable for implementation" was only described in one sentence, buried in a section that listed the available annotations. For consistency with other guarantees, this is now phrases as a positive thing rather than a negative thing. Especially considering that it only applies to interfaces, which are already unstable by default. See Stable to type.

---