On 11-09-15 05:06 AM, Andrew Garrett wrote:
On Thu, Sep 15, 2011 at 12:29 PM, Daniel Friesen
<lists(a)nadir-seen-fire.com> wrote:
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.
I don't like this. Old interfaces should be
either removed or fully
supported to the extent that the interface allows. We can't spend our
lives going around and changing code to fit some new-fangled interface
when you can just make the old interfaces a wrapper around the new
ones.
Except that's what we do. We create new interfaces replacing interfaces
that can't be used to work the way we want them to (ResourceLoader,
SkinTemplate's headelement key, methods that are stuck using $wg globals
with potential side effects when they should be getting state from their
caller, etc...) and we mark the old one deprecated while attempting to
leave some temporary partially working compatibility so that extensions
have time to update instead of breaking right away.
And as for fully removed, that's the ultimate goal of deprecating
something. You create a better interface and mark the old one deprecated
and try to make it work as much as possible (which since the new
interface was created to fix issues in the old one likely means that the
interface is only partially capable of working the way it should).
Extension maintainers start getting warnings and others help out
gradually changing extensions to use the new interface. And in a few
releases when you think most of the uses of that old flawed interface
are gone you remove it.
Supporting half functional interfaces forever isn't really an option.
We'd never have everything going through the resource loader. We'll
never be able to create a RequestContext and execute something into it
without having to screw with state globals. We'll never be able to have
more than one Parser instance because we'd still be supporting the case
where some extensions only apply to one parser. ... etc, that's
basically saying any project trying to fix the bad parts of our
interfaces that stop us from doing some things are pointless.
I'll I'm suggesting is that we start adding wfDeprecated right away
instead of a release or so later, and annotating it with the release
that it was deprecated. That way people who have a reason to ignore them
can ignore them, they can also get an idea of how urgent it is to fix
(deprecated in stable vs. deprecated in unreleased trunk), and
developers can actually start getting notices earlier that they are
using interfaces that they should migrate away from.
~Daniel Friesen (Dantman, Nadir-Seen-Fire) [
http://daniel.friesen.name]