Reading/Web/Working with legacy code

This page documents our experiences with working with modernizing legacy code.

Migrating code for ES6 compatible Promises

 * For consistency, prefer to use  when replacing   or  . Be aware of the return value in your callbacks though!
 * In general,  can be replaced with
 * Be aware of Deferred handlers with multiple parameters. A Deferred can resolve with multiple arguments passed to its callback functions while a ES6 promise can only resolve with only one argument.
 * When changing the return value of a function, keep in mind that  returns a JQuery.Deferred, but   returns a JQuery.Promise so you may have to update the JSDocs.
 * You may need to convert tests from sync to async if the tests cover code that previously relied on .done/.fail. This is because .done/.fail callbacks may be called synchronously if the Deferred has already been resolved (which is often the case with test stubs), but .then/.catch callbacks are always called asynchronously. See https://jquery.com/upgrade-guide/3.0/#backwards-compatibility for more info and https://github.com/wikimedia/mediawiki-extensions-MobileFrontend/commit/d42523e609082c300081149f5b9dde1ad6b4ced1#diff-057379d6c79b6705c76c0090f5685011 for an example
 * ESLint can be leveraged to forbid future usages of done, fail and always