For awhile now we've had this pattern for deprecating interfaces: * Mark it deprecated with @deprecated when you deprecate it * In one or two releases add wfDeprecated * A release or two after that or more remove the interface entirely
The rationale of not adding wfDeprecated seams to be so we don't spew warnings about recently deprecated methods to developers. ((Although after a discussion with Krinkle in #mediawiki we had a hard time justifying even that)) The fault of that pattern however is that as releases take time to come out by the time that the next release, or even the release after that, comes by developers have forgotten about the deprecation and forget to add the wfDeprecated for code they changed months ago and don't care about anymore. And the interfaces continue to be used without any notices to help notify people they're still using a deprecated interface which may only be half-functional. So, I've come up with an idea for a new pattern and committed a change to wfDeprecated. wfDeprecated now accepts a second arg, the version in which the method was deprecated. You can start use it like so: `wfDeprecated( __METHOD__, '1.19' );` When you use the version arg the notice will include information on when the method was deprecated. Additionally there is a new config setting $wgDeprecationReleaseLimit. If set to a release string alongside $wgDevelopmentWarnings then deprecation notices for releases later than the limit will not be outputted. eg: If you set $wgDeprecationReleaseLimit to "1.18" then `wfDeprecated( __METHOD__, '1.17' );` and `wfDeprecated( __METHOD__, '1.18' );` will generate notices, but `wfDeprecated( __METHOD__, '1.19' );` calls will stay silent. Additionally I've taken branches into account, if you're working in a branch (not a release branch) then please use the pattern: `wfDeprecated( __METHOD__, '1.19-branchname' );` Where 1.19 is likely whatever version trunk is currently at which you are merging from, and branchname is the name of your branch. This pattern will make it easy to search and replace that string when you merge that branch into trunk and will prevent traps like starting a branch in 1.19 and adding wfDeprecated calls with 1.19 as the version, but then actually merging it into trunk when trunk is 1.20 and having to go through each 1.19 tagged wfDeprecated and differentiate between the wfDeprecated calls you added and the wfDeprecated calls that were actually added in 1.19. Now instead of waiting for a later release I encourage developers to add the wfDeprecated calls right away when you deprecate something. If recent deprecations are too much noise for anyone they can just change the limit to what notices they get. https://secure.wikimedia.org/wikipedia/mediawiki/wiki/Special:Code/MediaWiki/97136 -- ~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name] _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
