The SIP has detailed instructions for deprecating calls to a method, but no guidance regarding deprecating method overrides. This task aims to fill that gap.
Prior art: T193613: RFC: Establish stable interface policy for PHP code, T255803: RFC: Amendment to the Stable interface policy, June 2020.

The issue

Deprecating method overrides is different from method calls. The dependency is inverted:

*this: deprecating class

In the case of normal method deprecation the method is defined in the deprecating class and the caller can be any code.
In the case of method override deprecation the method is defined by an unknown subclass and the caller of the (virtual) method is usually the deprecating (super)class (but can be any code).

Solution

T267080: Helper for deprecating method overrides (Patch 638202)

Method override deprecation requires a different approach:

• The inherited method is not necessarily called, thus the deprecation code cannot be in the method.
• An overridden method is not required to alter the program state differently from the inherited method, therefore whether a method is overridden cannot be determined with standard program flow.
• Reflection (metaprogramming) is used to determine the presence of an override.

Motivating example

T266735: Fix or archive skin using deprecated Skin::setupSkinUserCss() method (Patch 638203)

Documentation

This ticket is about formalizing the rules of deprecating method overrides in the SIP.

• The inherited method might be called by the override, therefore it cannot be removed.
• The inherited method is not necessarily called, thus the deprecation code cannot be in the method.
• The deprecation code should be in an initialization function: constructors might be run before the page headers are sent, generating the deprecation warning too early.

The deprecation code is (details in patch 638202):

use DeprecateOverridesHelper;
...
$this->deprecateMethodOverride( 'deprecatedMethod', '1.36', __CLASS__ );

Question

In what form should this be presented in the SIP?