Topic on Talk:Stable interface policy

Wording clarified by James.

The policy seems to suggest or assume that being @stable and @deprecated are mutually exclusive. Some stability types explicitly state this (such as stable to call and stable to type), in others it seems to be implied (e.g. stable to extend: Only classes that are marked @stable to extend).

To make this clearer, I suggest adding a bullet point similar to the following to the section on soft deprecation:

• Soft deprecated code SHOULD NOT be marked stable. Any @stable annotations should be removed at the same time that a @deprecated annotation is added.

And maybe also this to the section on hard deprecation:

• Hard deprecated code MUST NOT be marked stable.

I agree that they are mutually exclusive and that @stable should be removed upon deprecation. If this gets added to the official policy, it might be worth having a codesniffer warning for both @stable and @deprecated in the same doc block.

I agree that we should remove them on deprecation, but perhaps in our @deprecated tags we should explicitly say that it used to be stable to extend/etc.?

Hm, I just noticed this in Stable interface policy § Add guarantees:

The @stable annotations can be followed by a Deprecated since segment to indicate that a particular use of the class or method is currently deprecated. This can be used to indicate that extensions should no longer subclass, but may still call public methods. This guruantee may then be removed in the next release. Note that there is currently no hard-deprecation for the removal of stability guarantees.

/**
 * @stable to extend Deprecated since 1.35
 */
class Foo {
    /* … */
}

Not sure what that means for this proposal…

Hmm. Perhaps @DKinzler (WMF) can suggest how he saw this working?

I think it should work as follows:

When the intent is to remove, then `@stable` should just be replaced by `@deprecated`. No code should use it.

If the intend is to keep but make internal, `@stable` can have a "deprecated since" qualifier added. This prevents internal use of the affected code from being flagged as deprecated by IDEs and other tooling, while giving extensions authors at least some warning. It's basically "deprecated for public use but ok to use internally".

Thanks, that seems reasonable. I've tweaked the wording; hope this is correct and uncontroversial?

Yes, thank you!