From: Timo Tijhof Date: Sun, 24 Mar 2019 19:29:46 +0000 (+0000) Subject: resources: Improve foreign-resources docs and error messages X-Git-Tag: 1.34.0-rc.0~2368^2 X-Git-Url: http://git.cyclocoop.org/data/File:Image2.gif?a=commitdiff_plain;h=dd6beafe618f28a2e6f8ed8de74f9152f014afc5;p=lhc%2Fweb%2Fwiklou.git resources: Improve foreign-resources docs and error messages Previously, the help message was only shown when invoking the script without parameters. Now, if invoking it with incorrect or mispelled parameters, it shows what you can do instead (and no more exception trace, which it did before). Also document clearly but briefly how to use it, and with examples. Change-Id: Ib5ba3dc02c54039495a33d6e0cc4d026ca708ba1 --- diff --git a/includes/ForeignResourceManager.php b/includes/ForeignResourceManager.php index e0d088a916..297200e9ba 100644 --- a/includes/ForeignResourceManager.php +++ b/includes/ForeignResourceManager.php @@ -69,8 +69,10 @@ class ForeignResourceManager { * @throws Exception */ public function run( $action, $module ) { - if ( !in_array( $action, [ 'update', 'verify', 'make-sri' ] ) ) { - throw new Exception( 'Invalid action parameter.' ); + $actions = [ 'update', 'verify', 'make-sri' ]; + if ( !in_array( $action, $actions ) ) { + $this->error( "Invalid action.\n\nMust be one of " . implode( ', ', $actions ) . '.' ); + return false; } $this->action = $action; @@ -80,7 +82,11 @@ class ForeignResourceManager { } elseif ( isset( $registry[ $module ] ) ) { $modules = [ $module => $registry[ $module ] ]; } else { - throw new Exception( 'Unknown module name.' ); + $this->error( "Unknown module name.\n\nMust be one of:\n" . + wordwrap( implode( ', ', array_keys( $registry ) ), 80 ) . + '.' + ); + return false; } foreach ( $modules as $moduleName => $info ) { diff --git a/maintenance/manageForeignResources.php b/maintenance/manageForeignResources.php index 87f2e83144..54554b8c5b 100644 --- a/maintenance/manageForeignResources.php +++ b/maintenance/manageForeignResources.php @@ -33,14 +33,20 @@ class ManageForeignResources extends Maintenance { $this->addDescription( <<addArg( 'action', 'One of "update", "verify" or "make-sri"', true ); diff --git a/resources/lib/foreign-resources.yaml b/resources/lib/foreign-resources.yaml index d4458aa905..f862850bbe 100644 --- a/resources/lib/foreign-resources.yaml +++ b/resources/lib/foreign-resources.yaml @@ -1,38 +1,92 @@ -### Format of this file +# ## Format of this file # -# The top-level keys are directory names (under resources/lib/). -# They should match module names (as registered in Resources.php), but there are exceptions. -# Each top-level key holds a resource descriptor that must have one of -# the following `type` values: +# The top-level keys in this file correspond with directories under resources/lib/. +# These in turn are registered as module bundles in Resources.php. # -# - `tar`: For tarball archive (may be gzip-compressed). -# - `file: For a plain file. -# - `multi-file`: For multiple plain files. +# ## How to install an foreign resource +# +# 1. Add or update the url(s) for the upstream module to this YAML file. +# +# Look at other modules for examples. To install a module from npm, +# we use the tarball distribution from npmjs.org. This is the same as what +# the npm CLI uses. For example, to install jquery-client@9.2.0, use: +# . +# +# 2. If the upstream maintainers publish an integrity hash, set that as well. +# Otherwise, use manageForeignResources.php to compute the integrity hash. +# +# Run `php manageForeignResources.php make-sri "my module name"` # -### Type tar +# This will download the specified file(s) and print their integrity hashes, +# already formatted in YAML, ready for copying to this file. # -# The `src` and `integrity` keys are required. +# 3. Last but not least, decide where files go. +# +# If you specified a direct url to JavaScript or CSS file, this step is +# optional. See the corresponding documentation section below for more +# information and examples for "dest" keys. Once you've set any "dest" keys, +# run `php manageForeignResources.php update "my module name"`. +# +# ## Package formats +# +# Each top-level key must use one of these types: +# +# - `file`: For a plain file. +# - `multi-file`: For multiple plain files. +# - `tar`: For a tarball archive (may be compressed). +# +# ### The "file" type # # * `src`: Full URL to the remote resource. # * `integrity`: Cryptographic hash (integrity metadata format per ). -# * `dest`: An object mapping paths to files or directory from the remote resource to a destination -# in the module directory. The value of key in dest may be omitted, which will extract the key -# directly to the module directory. +# * `dest`: [optional] The file name to use in the module directory. Default: Basename of URL. +# +# For example, the following would produce resources/lib/mymodule/x.js: +# +# mymodule: +# type: file +# src: https://mymodule.example/1.2.3/x.js +# integrity: sha384-Je+NE+saisQuoi # -### Type file +# ### The "multi-file" type # -# The `src` and `integrity` keys are required. +# * `files`: An object mapping destination paths to `src` and `integrity` keys. +# +# For example: +# +# mymodule: +# type: multi-file +# files: +# x.js: +# src: https://mymodule.example/1.2.3/x.js +# integrity: sha384-Je+NE+saisQuoi +# x.css: +# src: https://mymodule.example/1.2.3/x.css +# integrity: sha384-Je+NE+saisQuoi +# +# ### The "tar" type # # * `src`: Full URL to the remote resource. # * `integrity`: Cryptographic hash (integrity metadata format per ). -# * `dest`: The name of the file in the module directory. Default: Basename of URL. +# * `dest`: [optional] The default is to extract all files from the package. +# To only extract some of the files or directories, use "dest" to specify +# files, directories, and/or glob patterns. You can use a site like https://unpkg.com/ +# to easily inspect an npm package, like . +# +# For example: # -### Type multi-file +# mymodule: +# type: tar +# src: https://registry.npmjs.org/jquery-client/-/jquery-client-9.2.0.tgz +# integrity: sha384-Je+NE+saisQuoi +# dest: +# package/dist/x.js: +# package/dist/i18n: +# package/dist/style/*.css: # -# The `files` key is required. +# The would extract the "x.js" file, the "i18n" directory (recursive), +# and any "*.css" files from the "style" directory. # -# * `files`: An object mapping destination paths to an object containing `src` and `integrity` -# keys. CLDRPluralRuleParser: type: file @@ -94,31 +148,26 @@ jquery.form: type: file src: https://raw.githubusercontent.com/jquery-form/form/ff80d9ddf4/jquery.form.js integrity: sha384-h4G2CrcSbixzMvrrK259cNBYaL/vS1D4+KdUN9NJDzQnTU1bQ6Avluget+Id13M7 - dest: jquery.form.js jquery.fullscreen: type: file src: https://raw.githubusercontent.com/theopolisme/jquery-fullscreen/v2.1.0/jquery.fullscreen.js integrity: sha384-G4KPs2d99tgcsyUnJ3eeZ1r2hEKDwZfc4+/xowL/LIemq2VVwEE8HpVAWt4WYNLR - dest: jquery.fullscreen.js jquery.hoverIntent: type: file src: https://raw.githubusercontent.com/briancherne/jquery-hoverIntent/823603fdac/jquery.hoverIntent.js integrity: sha384-lca0haN0hqFGGh2aYUhtAgX9dhVHfQnTADH4svDeM6gcXnL7aFGeAi1NYwipDMyS - dest: jquery.hoverIntent.js jquery.jStorage: type: file src: https://raw.githubusercontent.com/andris9/jStorage/v0.4.12/jstorage.js integrity: sha384-geMeN8k803kPp6cqRL4VNfuSM1L8DcbKRk0St/KHJzxgpX9S0y9FA6HxA/JgucrJ - dest: jstorage.js jquery.throttle-debounce: type: file src: https://raw.githubusercontent.com/cowboy/jquery-throttle-debounce/v1.1/jquery.ba-throttle-debounce.js integrity: sha384-ULOy4DbAghrCqRcrTJLXOY9e4gDpWh0BeEf6xMSL0VtNudXWggcb6AmrVrl4KDAP - dest: jquery.ba-throttle-debounce.js moment: type: tar