ResourceLoader/Requirements

Requirement	Features	Benefits	Issues
Debugging
Support direct resource inclusion	Allows JS resources to be included individually and without being run through the loader software	JS resources can be more easily debugged because file names and line numbers correspond to the actual JS resources	Requires L10n fallbacks to be embedded in JS resources
Support stand-alone use of loader	Allows the script loader system to be integrated into other frameworks or used as a stand-alone service	Development efforts can be shared with non-MediaWiki developers, and those developers' efforts can benefit us	Makes MediaWiki integration difficult, makes code more foreign to MediaWiki developers
Useful information on loading failure	Provides useful, verbose information about failures to load resources	Makes development easier	Requires more code to be written
Packaging
Remove debug statements	Allows JS resources to contain debug information which is stripped out before being sent to the client	Debug information can remain in JS resources for future use	More moving parts to break
JS/CSS Minification	Strips whitespace and comments from JS and CSS resources	Reduces the amount of data sent to the client	Makes debugging more difficult
JS Closure Compilation	Simplifies and aggressively optimizes JS functions	Reduces the amount of data sent to the client, and improves the performance of many JS functions	Makes debugging very difficult
CSS Janus transformation	Flips CSS rules to make LTR stylesheets appropriate for RTL	No need to keep separate files around for this if we can apply this transformation in PHP along with the others	Makes it slightly more difficult to figure out what the RTL version of a given CSS file looks like
Resource batching / concatenation	Multiple resources can be included in a single request	Reduces the number of requests from clients	Potentially increases cache size, potentially causes double inclusion of resources
Parameterize batched loading	Set a URL param to indicate we need resources for a certain combination of prefs/logged-in-ness rather than detecting this on the server	Eliminates the need for uncacheable-for-logged-in-users Vary: Cookie responses	Increases the number of URL variants
Web-server-level resource caching	Caches processed (localized, minified, etc.) scripts on the server	Makes it faster to batch resources in different combination	Caching is not free, it takes time and space
Use short client-side expiry times	Tells clients to refresh cached resources in short intervals (~1h)	Eliminates the need to expire HTML (expensive) to force clients to refresh resources	Requires that RL requests be cheap, so they should support 304 and be cached in Squid
Use highest-timestamp versioning scheme	Version each RL request with the highest last-modified timestamp of the resources involved, formatted in ISO 8601 and rounded to 10s	No more manual style versions. 10s rounding and human-readable format allows faster and easier purging of bad resources from Squid	May cause conflicts when new JS is served with old HTML, need to code around that in JS
In-place localization	Includes localized messages directly within JS resources	Allows i18n of JS software without adding additional requests	Mixes i18n work with development work
Localization API	Makes messages available on demand individually or in groups	Provides yet another option for getting L10n to the client	Very inefficient way to get L10n to the client
Separate message resource system	Generates JS blobs for l10n separately, stores them in the DB	Only relevant JS is regenerated when a message changes	Makes stand-alone usage more difficult
Export user preferences to JS
CSS grouping (without JS)
CSS includes registered in JS namespace	Allows JS resources to check existence of CSS resources and require CSS resources to be loaded before proceeding	Fewer CSS resources need to be included initially and modules can safely avoid re-loading already-loaded CSS resources	Requires more code to be written
Resource buckets	Allows resources to be grouped into buckets such as "all", "view", "edit", etc.	Reduces number of individual requests needed	Potentially too many things will get put in these buckets
Runtime loading of JS and CSS	Allows resources to be included dynamically	Reduces the initial payload sent to clients	Potentially presents delay between user action and resource availability
Module based loading	Resources are identified by module names	Provides a standard way of expressing requirements and checking what resources are already loaded
Module loaders	Modules each have associated loader functions which are executed to load the module	Provides more flexibility in loading	Increases the amount of code sent to the client and level of complexity in development
Configurable URL scheme	Allows flexibility in request URL formats	Makes using a localhost, web-server or CDN a matter of configuration
Allow version aliasing	In the case that a buggy version of a script is released, a version redirect can be put in place	Avoids purging PHP generated HTML to resolve JS bugs	Potentially introduces level of indirection causing negative performance impact. Not needed if scripts are versioned and cached in Squid
Dependency order preservation	Allows dependencies to automatically be included in a specific order if needed	Makes dependencies simpler to use	May make dependency specification more complex
Structure
Clear division of libraries	Makes JS resources communicate with each other using well documented APIs	Improves the re-usability of JS resources	Takes more time to develop and document
Control a specific JS namespace	Specifies a unified naming convention and access point for JS resources	Improves maintainability and reduces difficulty to learn the system	Requires porting existing code to conform
Control naming between PHP and JS resources	Specifies clear naming between PHP extensions and JS modules	Improves maintainability and reduces difficulty to learn the system	Requires porting existing code to conform
Package-level dependency resolution	JS modules can form packages, which can then be required/included as a whole	Reduces complexity of specifying requirements making development easier	Reduces specificity of requirements potentially causing resources to be loaded that will not be used
Map files, buckets and dependencies in PHP	Have an associative array structure in PHP that defines objects, which optionally contain a file and optionally have dependencies	Makes for fewer distinct URLs (?), which eases caching and purging	Limited support for JS-based conditions, would have to be done through parameterization, cannot scale to user scripts
Division between loading and execution	JS modules can be loaded on demand, and executed independently	Makes dependencies simpler to use	Makes writing modules more complex
Allow explicit re-loading	Resources are not loaded more than once by default, but can be re-loaded if desired	Makes overwriting/re-loading possible/easier
jQuery should be the primary way of extending functionality
jQuery plug-ins should be centrally organized	All jQuery plug-ins should be committed to a central place, with version numbers in their names	Makes sharing plug-ins easier / more likely to happen and everyone benefits from bug-fixes equally	Causes issues with maintaining extensions or if people cloud the plug-in folder with low-quality plug-ins
JS module version conflict management	Makes module version information available to JS resources	Makes it possible to migrate to newer versions of plug-ins over time	Sends more data to the client, adds complexity to configuration
Utilities
JS localization functions	JS facilities for handling 18n functionality such as {{PLURAL}} and $ replacement	Messages can be more flexible and reusable	Must be maintained in parallel with PHP i18n functions, limitations must be well understood by translators

Sources

This document is a synthesis of the following sources