Change Details

The [[ https://www.mediawiki.org/wiki/Stable_interface_policy#Deprecation | SIF ]] has detailed instructions for deprecating calls to a method, but no guidance regarding deprecating method overrides. This task aims to fill that gap. Last amendment: {T255803}. === The issue Deprecating method overrides is different from method calls. The dependency is **inverted**: | | owner | caller | |method deprecation| this class | other code |override deprecation| other (subclass) | this (superclass) *//this//: deprecating class In the case of normal method deprecation the method is defined in the deprecating class and the caller is the unknown class. In the case of method override deprecation the caller of the method is the deprecating (super)class usually and the method is defined by an unknown class. === Solution {T267080} (Patch [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638202|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} (Patch [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638203|638203]]) === Documentation This ticket is about formalizing the rules of deprecating method overrides in the SIF. * **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 [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638202|638202]]): ``` use DeprecateOverridesHelper; ... $this->deprecateMethodOverride( 'deprecatedMethod', '1.36', __CLASS__ ); ``` === Question In what form should this be presented in the SIF?

The [[ https://www.mediawiki.org/wiki/Stable_interface_policy#Deprecation | SIF ]] 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}, {T255803}. === The issue Deprecating method overrides is different from method calls. The dependency is **inverted**: | | owner | caller | |method deprecation| this class | other code |override deprecation| other (subclass) | this (superclass) *//this//: deprecating class In the case of normal method deprecation the method is defined in the deprecating class and the caller is the unknown class. In the case of method override deprecation the caller of the method is the deprecating (super)class usually and the method is defined by an unknown class. === Solution {T267080} (Patch [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638202|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} (Patch [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638203|638203]]) === Documentation This ticket is about formalizing the rules of deprecating method overrides in the SIF. * **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 [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638202|638202]]): ``` use DeprecateOverridesHelper; ... $this->deprecateMethodOverride( 'deprecatedMethod', '1.36', __CLASS__ ); ``` === Question In what form should this be presented in the SIF?

The [[ https://www.mediawiki.org/wiki/Stable_interface_policy#Deprecation | SIF ]] has detailed instructions for deprecating calls to a method, but no guidance regarding deprecating method overrides. This task aims to fill that gap. Last amendment:Prior art: {T193613}, {T255803}. === The issue Deprecating method overrides is different from method calls. The dependency is **inverted**: | | owner | caller | |method deprecation| this class | other code |override deprecation| other (subclass) | this (superclass) *//this//: deprecating class In the case of normal method deprecation the method is defined in the deprecating class and the caller is the unknown class. In the case of method override deprecation the caller of the method is the deprecating (super)class usually and the method is defined by an unknown class. === Solution {T267080} (Patch [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638202|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} (Patch [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638203|638203]]) === Documentation This ticket is about formalizing the rules of deprecating method overrides in the SIF. * **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 [[https://gerrit.wikimedia.org/r/c/mediawiki/core/+/638202|638202]]): ``` use DeprecateOverridesHelper; ... $this->deprecateMethodOverride( 'deprecatedMethod', '1.36', __CLASS__ ); ``` === Question In what form should this be presented in the SIF?