resourceloader: Soft-deprecate use of global LESS variables

Add deprecation notice to $wgResourceLoaderLESSVars and
hook 'ResourceLoaderGetLessVars'. Warnings to be added in 1.31.

Users should migrate to exposing variables via the individual module's
getLessVars() method.
- Ensures better cache invalidation.
- Separates concerns for getting information and exposing information
  as less variables. And allows an extension to, for example, use
  a different variable name for something if needed.

The 'deviceWidthTablet' variable will need to be migrated to
either a regular configuration variable that individual modules
can expose in their getLessVars() method - or, alternatively, we
can deprecate it altogether in favour of exposing it through
a less import file instead (see T112747). That would mean, however,
that the value can only be changed in core, not by site config.

Bug: T140804
Change-Id: I61cff1d9652d88dc53c43075dd5053b7707809e6

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 3ff3365..8912b82 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -2764,9 +2764,10 @@ configuration variables to JavaScript. Things that depend on the current page
 or request state must be added through MakeGlobalVariablesScript instead.
 &$vars: array( variable name => value )
 
-'ResourceLoaderGetLessVars': Called in ResourceLoader::getLessVars after
-variables from $wgResourceLoaderLESSVars are added. Can be used to add
-context-based variables.
+'ResourceLoaderGetLessVars': DEPRECATED! Called in ResourceLoader::getLessVars
+to add global LESS variables. Loaded after $wgResourceLoaderLESSVars is added.
+Global LESS variables are deprecated. Use ResourceLoaderModule::getLessVars()
+instead to expose variables only in modules that need them.
 &$lessVars: array of variables already added
 
 'ResourceLoaderJqueryMsgModuleMagicWords': Called in

diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index f35715e..b5c90d3 100644 (file)
--- a/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@ -3754,20 +3754,18 @@ $wgResourceLoaderValidateStaticJS = false;
  * at the beginning of all your .less files, with all the consequences.
  * In particular, string values must be escaped and quoted.
  *
- * Changes to LESS variables do not trigger cache invalidation.
- *
- * If the LESS variables need to be dynamic, you can use the
- * ResourceLoaderGetLessVars hook (since 1.25).
+ * Changes to this configuration do NOT trigger cache invalidation.
  *
  * @par Example:
  * @code
  *   $wgResourceLoaderLESSVars = [
- *     'baseFontSize'  => '1em',
- *     'smallFontSize' => '0.75em',
- *     'WikimediaBlue' => '#006699',
+ *     'exampleFontSize'  => '1em',
+ *     'exampleBlue' => '#eee',
  *   ];
  * @endcode
  * @since 1.22
+ * @deprecated since 1.30 Use ResourceLoaderModule::getLessVars() instead to
+ *  add variables to individual modules that need them.
  */
 $wgResourceLoaderLESSVars = [
        /**