Topic on Talk:ResourceLoader/Legacy JavaScript

See T35836 and T122755.

See also bugzilla:33836 and bugzilla:29753

---

The original plan (as somewhat documented on pages like ResourceLoader/JavaScript Deprecations) was as following:

1) Deprecation

• Baptize scripts in /skins/common deprecated (wikbits.js, ajax.js etc.; "legacy JS")
• Start working on mediawiki object library
• Work step-by-step on removing any and all references to legacy JS in MediaWiki core by either superseding/rewriting/modernizing them with new utilities in the mw object or by replacing them with calls to jQuery core or plugin methods.
• End up in a situation where there are no references to legacy JS in MediaWiki core anymore. At this point all of it's functionality will be redundant or made possible by other means (jQuery core, plugins or mediawiki object). However at this point, all of the legacy functionality should still be available and work like it did before.

2) Migration

• At this point users should start en-mass with migrating scripts (1.17 deployment). It will be highly encouraged to switch to more modern implementations of legacy features as soon as possible.

3) Quarantine

• After a few releases (around 1.20 branch?) the legacy JS will be moved from the global scope into a quarantined scope in mw.legacy. Remapping may be used as a stop-gap until for example pending bugs in mediawiki lib are being fixed or other issues solved. Stop-gap being replacing calls from foo with mw.legacy.foo etc.

4) Removal of legacy code entirely.

There are many scripts using things like addPortletlink, sajax_*, updateTooltipAccessKeys, checkboxShiftClick and more. While I agree that having code like this, code that is not used in core, has a future version that is said to be better and mostly compatible, etc, sounds weird.

But removing a legacy method as soon as there is a better version and telling users to fix their scripts doesn't like a plan either, see the above.

Also note that legacy scripts don't have unit tests, and likely never will because they are pending to be removed, will never change anyway, and are (ab)used in so many different ways due to lack of documentation or examples, so it wouldn't represent usage of the methods in the real-world.

Legacy code that is no longer being actively used by core should be removed entirely.

Where there are legacy function & variable APIs that we can cleanly make shims for, it's very nice to be able to make available. Where there aren't, keeping the old code as-is in a "legacy quarantine" doesn't make much sense to me, as anything attempting to call them will still have to jump through hoops to find the quarantine module and use it in the first place... and then much of the time they may end up failing as they're out of date with the rest of the interface.

Our current situation per bugzilla:29753 is that "legacy" code in wikibits.js is still:

• included in core
• always loaded
• actively used by core

and there's "new code" to replace it which is:

• not loaded at all
• not used at all

ergo, it's not a case of legacy code that's been superseded -- it's active live code still in active live use.

The course of action I recommend is to finish that job: load and use the new code, remove the old code, and supply a compatibility shim for the old var/function if anything needs it.

I love a man who uses "shim." What a great word.