TL;DR: * Review site scripts to verify that no wikibits methods[1] are used. * If you find usage of wikibits, refactor the code to use newer methods instead, or add a dependency on the 'mediawiki.legacy.wikibits' module.
Hi all,
The deprecation and eventual removal of the legacy "wikibits" JavaScript module has been a long time coming. This announces another step in that direction.
In 2011, wikibits was deprecated following the introduction of ResourceLoader in MediaWiki 1.17. To accommodate pre-ResourceLoader code that doesn't have a concept of dependencies, $wgIncludeLegacyJavaScript was created to allow existing sites (such as Wikimedia wikis) to load "mediawiki.legacy.wikibits" by default on all pages. While most code no longer uses wikibits, it remains set to this day.
In 2013, we introduced mw.log.deprecate in MediaWiki 1.23 to help you detect any use of deprecated methods in the browser's developer console.[2] We have seen a big reduction in the use of such methods.[3]
In 2015, we made significant performance improvements in MediaWiki 1.26, by running JavaScript asynchronously rather than blocking page rendering. To avoid breaking undeclared use of wikibits, we made an exception for wikibits and kept it as blocking other JavaScript modules on page views, re-purposing $wgIncludeLegacyJavaScript to mean "always load wikibits before other modules".
Now, as the last step before removing wikibits from MediaWiki, it will first no longer load by default in MediaWiki 1.27. This change will roll out on Wikimedia wikis in April 2016. If you find usage of wikibits features without a dependency, please refactor this code to use the modern replacements[1], or add an explicit dependency as temporary stop-gap while figuring out how to refactor the code.
Before re-factoring, please remember to first check whether the associated code is working. Many wikibits methods have become empty placeholders to avoid cascading failures. As such, blind updates may cause old or broken code that is currently invisible to re-activate itself. Removing dead code speeds up wikis for all users, and reduces the risk of things going wrong in future.
For third-party wikis, this will ship in MediaWiki 1.27.0. If needed, you can alter LocalSettings.php and set $wgIncludeLegacyJavaScript to true. This will give you time to fix missing dependencies on wikibits. In MediaWiki 1.28, to be released in November 2016, the wikibits module will be removed entirely.
-- Krinkle
[1] https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript [2] https://lists.wikimedia.org/pipermail/wikitech-l/2013-October/072776.html [3] https://grafana.wikimedia.org/dashboard/db/mw-js-deprecate?from=now-10M
So eh.. what are we doing with this part then:
// Not quite deprecated yet. win.importScript = importScript; win.importStylesheet = importStylesheet;
On 26 mrt. 2016, at 00:19, Krinkle krinklemail@gmail.com wrote:
TL;DR:
- Review site scripts to verify that no wikibits methods[1] are used.
- If you find usage of wikibits, refactor the code to use newer methods
instead, or add a dependency on the 'mediawiki.legacy.wikibits' module.
Hi all,
The deprecation and eventual removal of the legacy "wikibits" JavaScript module has been a long time coming. This announces another step in that direction.
In 2011, wikibits was deprecated following the introduction of ResourceLoader in MediaWiki 1.17. To accommodate pre-ResourceLoader code that doesn't have a concept of dependencies, $wgIncludeLegacyJavaScript was created to allow existing sites (such as Wikimedia wikis) to load "mediawiki.legacy.wikibits" by default on all pages. While most code no longer uses wikibits, it remains set to this day.
In 2013, we introduced mw.log.deprecate in MediaWiki 1.23 to help you detect any use of deprecated methods in the browser's developer console.[2] We have seen a big reduction in the use of such methods.[3]
In 2015, we made significant performance improvements in MediaWiki 1.26, by running JavaScript asynchronously rather than blocking page rendering. To avoid breaking undeclared use of wikibits, we made an exception for wikibits and kept it as blocking other JavaScript modules on page views, re-purposing $wgIncludeLegacyJavaScript to mean "always load wikibits before other modules".
Now, as the last step before removing wikibits from MediaWiki, it will first no longer load by default in MediaWiki 1.27. This change will roll out on Wikimedia wikis in April 2016. If you find usage of wikibits features without a dependency, please refactor this code to use the modern replacements[1], or add an explicit dependency as temporary stop-gap while figuring out how to refactor the code.
Before re-factoring, please remember to first check whether the associated code is working. Many wikibits methods have become empty placeholders to avoid cascading failures. As such, blind updates may cause old or broken code that is currently invisible to re-activate itself. Removing dead code speeds up wikis for all users, and reduces the risk of things going wrong in future.
For third-party wikis, this will ship in MediaWiki 1.27.0. If needed, you can alter LocalSettings.php and set $wgIncludeLegacyJavaScript to true. This will give you time to fix missing dependencies on wikibits. In MediaWiki 1.28, to be released in November 2016, the wikibits module will be removed entirely.
-- Krinkle
[1] https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript [2] https://lists.wikimedia.org/pipermail/wikitech-l/2013-October/072776.html [3] https://grafana.wikimedia.org/dashboard/db/mw-js-deprecate?from=now-10M _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
I think we are going to need more than a month to fix this. A search on enwiki shows 26,000 pages using importScript, 7,000 pages using addOnloadHook, and 4,000 pages using addPortletLink. (Although addPortletLink is already aliased to mw.util.addPortletLink in enwiki's Mediawiki:Common.js.) It would also be nice to have a drop-in replacement for importScript before we disable it - I can imagine a lot of users getting annoyed at having to change all their importScript calls to the mw.loader.load syntax.
Strad
It should be noted that a significant portion of those user pages, might not effectively be in use, since the user has since stopped using Wikipedia itself.
DJ
On 27 mrt. 2016, at 17:23, Mr. Stradivarius misterstrad@gmail.com wrote:
I think we are going to need more than a month to fix this. A search on enwiki shows 26,000 pages using importScript, 7,000 pages using addOnloadHook, and 4,000 pages using addPortletLink. (Although addPortletLink is already aliased to mw.util.addPortletLink in enwiki's Mediawiki:Common.js.) It would also be nice to have a drop-in replacement for importScript before we disable it - I can imagine a lot of users getting annoyed at having to change all their importScript calls to the mw.loader.load syntax.
Strad _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
This has been in the works for *years* now. How much more time do we need already?
I'd rather see a replacement as well, as .mw.loader.laod is somewhat unintuitive having to specify the entire raw url. Why does mw.util (or mw.loader) not have a function to build such an url like importScript has?
Regards,
On Mon, Mar 28, 2016 at 5:07 AM, Erwin Dokter erwin@darcoury.nl wrote:
This has been in the works for *years* now. How much more time do we need already?
It's been in the works for years, yes, but there hasn't been a specific time-frame for removal before, and the deprecation hasn't been as widely publicised on the wikis as it could have been. Now that we have a specific time-frame we see people on e.g. enwiki's technical village pump [1] discussing in earnest what should be done, but there hasn't been this type of discussion on this issue on enwiki before to my knowledge.
Fixing this properly would require a lot of things to happen. For example, I think we will need: * A clear guide on how to update the deprecated code. The mailing list announcement [2] and the legacy javascript page [3] are a good start, but having one document with code examples that is specific to the change would make it easier for less experienced script writers to work out how to update their code. * A short, easy-to-understand guide for end users who are just loading scripts with importScript. * A list of which users are affected, and what scripts they would need to fix. * A bot / MassMessage run to notify all of these users that there is something they need to fix. * A list of unmaintained scripts that need to be fixed by community members. (If there is a way to figure out which pre-Gadgets-2.0 scripts are actually in use, then even better.)
With all of this machinery set in motion, I think we could make a sizable dent in the backlog of scripts that need fixing. However, I imagine that even with this, fixing everything that needs fixing would take more than a month. A lot depends on the number of unmaintained scripts and the difficulty of fixing them, and we also need to factor in things like requesting global interface editor rights, which takes one week at the moment.
Also, note that I'm not trying to imply that the things in the list above should be done by the WMF. Some or all of them could be handled by the community, but again, this would take time.
For those interested, I proposed some similar ideas to the above last year on Phabricator, as a standardised procedure of deprecating public-facing MediWiki code. [4]
Strad
[1] https://en.wikipedia.org/wiki/Wikipedia:Village_pump_%28technical%29#Breakin... [2] https://lists.wikimedia.org/pipermail/wikitech-l/2016-March/085113.html [3] https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript [4] https://phabricator.wikimedia.org/T114384
On Tue, Mar 29, 2016 at 5:05 AM, Mr. Stradivarius misterstrad@gmail.com wrote:
Fixing this properly would require a lot of things to happen. For example, I think we will need:
- A clear guide on how to update the deprecated code. The mailing list
announcement [2] and the legacy javascript page [3] are a good start, but having one document with code examples that is specific to the change would make it easier for less experienced script writers to work out how to update their code.
- A short, easy-to-understand guide for end users who are just loading
scripts with importScript.
[..]
https://en.wikipedia.org/wiki/Wikipedia:Village_pump_%28technical%29#Breakin... https://lists.wikimedia.org/pipermail/wikitech-l/2016-March/085113.html https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript
Thanks Strad. As mentioned, the mailing list and Tech News went out. I've gone ahead and updated these as well:
https://www.mediawiki.org/wiki/ResourceLoader/Migration_guide_%28users%29 https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript https://www.mediawiki.org/wiki/ResourceLoader/Modules#mediaWiki.loader
Usage in site-wide scripts (such as Common.js and Gadgets) are mostly updated already.
It's mainly user scripts that use importScript a lot. A massive find-and-replace from importScript to mw.loader.load() could be done.
However, for larger wikis it may be desirable to "simply" re-define importScript in MediaWiki:Common.js as shortcut for mw.loader.load. This is guaranteed to be available before any user modules.
A local definition allows wikis to migrate (or not) at their own pace. Either by a massive find/replace action in the future, or by informing users of particular scripts to replace one snippet with another (from a documentation page specific to that script). This is similar to how script authors may currently try to get users to update their installation (e.g. if the script moved or changed significantly).
However I do want to emphasise that for importScript in particular, there is no rush. If we need to keep an alias around indefinitely on most larger wiki's Common.js, that seems fine. Same for addOnloadHook (though that one is significantly easier to update).
The main thing we're trying to clean up here is the dozens of legacy global functions and variables that are largely unused. Such as 'clientPC', 'ie6_bugs', 'escapeQuotesHTML', 'killEvt' etc. And the negative performance impact of having to load it before all other modules.
On Tue, Mar 29, 2016 at 5:05 AM, Mr. Stradivarius misterstrad@gmail.com wrote:
- A list of which users are affected, and what scripts they would need to
fix.
I would advise against that. In my experience, the vast majority of user scripts are not "written" by users, but were composed of install instructions from another wiki page (e.g. "To enable X, copy this snippet to Special:MyPage/common.js, and save"). I don't think we should burden them with the updating of such snippet themselves.
However we should definitely reach out to authors of wiki pages (e.g. documentation pages for user scripts) to ensure that installation instructions and snippets are up-to-date.
-- Krinkle
[1] https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript
Krinkle wrote:
However I do want to emphasise that for importScript in particular, there is no rush. If we need to keep an alias around indefinitely on most larger wiki's Common.js, that seems fine. Same for addOnloadHook (though that one is significantly easier to update).
The main thing we're trying to clean up here is the dozens of legacy global functions and variables that are largely unused. Such as 'clientPC', 'ie6_bugs', 'escapeQuotesHTML', 'killEvt' etc. And the negative performance impact of having to load it before all other modules.
I don't understand this. If your main goal is to remove unused and unneeded legacy global variables and functions, and your examples such as 'ie6_bugs' and 'clientPC' seem like fine kill targets to me, why not just remove that code and leave used/useful code like 'importScript'?
I'm somewhat reminded of the minimum supported PHP version discussion and the remark about supporting software that can run on our own servers. While this is not directly analogous, if we're going to put a bunch of shims in place on "large" Wikimedia wikis, why not just keep supporting 'importScript' in wikibits? We can move the code to a more modern location in MediaWiki core, if desired.
If Wikimedia wikis are largely unable to do this full migration to updated syntax, it seems pretty unreasonable to expect every other MediaWiki installation to essentially copy and paste some snippet into their "MediaWiki:Common.js" page when updating MediaWiki to 1.28 in order to keep useful functions like 'importScript' working. You note that there's no rush, so why make this extra work for everyone? Can we just kill the largely unused portions of wikibits for now and wait till usage of the other code is acceptably low enough to properly remove? Or could we just have 'importScript' indefinitely be an alias for 'mw.loader.load', etc.?
MZMcBride
wikitech-l@lists.wikimedia.org