diff --git a/Working with DEWP.md b/Working with DEWP.md index 417849b116..0c400d1d1f 100644 --- a/Working with DEWP.md +++ b/Working with DEWP.md @@ -44,18 +44,50 @@ In a regular project to track outdated packages, you would use `npm outdated`. H ### What is the version of the DEWPed package? -As we externalize packages we lose control of the version of the package that will run in the wild (on WordPress instance). -However, with the current platform, we not only lose control, but we also lose the actual information on the range of package we should expect. -So, even if we know we support WooCommerce 6.9+, what are the `@woocommerce/components` there? +As we externalize a package, we lose control of its version that will run in the wild (on WordPress instance). +However, with the current platform, we not only lose control, but we also lose the actual information on the range of package versions we should expect. +So, even if we know we support WooCommerce L-2, what are the `@woocommerce/components` there? -There is no published table of those, and finding them usually requires quite a lot of manual digging. To mitigate that we created another script. +There is no published table of those, and finding them usually requires quite a lot of manual digging. To mitigate that, we created a tool: [`dewped`](https://github.com/woocommerce/dewped#dewped). -- `npm run dewps:woo 6.9.4` - where `6.9.4` is the version of WooCommerce you would like to check. +First, `latest-versions`/`l-x` helps you check the platform's current, latest, or L-x version: + +```bash +$ dewped l-x +Fetching L-2 versions wordpress! +["6.3.1","6.2.2","6.1.3"] + +$ dewped l-x woocommerce 3 +Fetching L-3 versions woocommerce! +["8.0.3","7.9.0","7.8.2","7.7.2"] +``` + +Then, with `platform-dependency-version`/`pdep` you may check which version of packages is expected to be present in the platform you target to support and compare it to the locally installed versions. + +```bash +$ dewped pdep -w=6.2.2 -c=7.8.2 -d=.externalized.json + Name WordPress 6.2.2 WooCommerce 7.8.2 Local + ────────────────────────────────── ─────────────── ───────────────── ──────── + @woocommerce/components 12.0.0 ^10.3.0 +… +``` + + +You can also use it to check an individual package. For example, when you consider adding a new dependency and want to check which version to anticipate + +```bash +$ dewped pdep --wcVersion=7.8.2 @woocommerce/data + Name WooCommerce 7.8.2 Local + ───────────────── ───────────────── ────── + @woocommerce/data 4.1.0 ^4.1.0 +``` + +Please bear in mind there are still dragons: +1. :warning: By the design of DEWP, there is absolutely no guarantee that the package will be there at the version reported by this tool. DEWP makes use of global variables available in runtime. So, any other extension or custom code running in a particular instance can overwrite what you expect in a package. +2. The fact that `dewped pdep package` reports a version of a package does not mean it was actually externalized from your bundle. It only means WP/WC uses a reported version. To check what was effectively externalized, please inspect your Webpack config and DEWP report file (`externalizedReport`). +3. Some packages externalized by DEWP, like `@woocommerce/settings`, are not packages we could find either in npm or in [`woocommerce/woocommerce/packages/js`](https://github.com/woocommerce/woocommerce/commits/trunk/packages/js/) 🤷. There may be no way for you to install them locally or even reason about their versions. +4. The `dewped` tool implementation relies on the internal structure of WordPress and WooCommerce repos, which is not documented, considered API, or even stable. So, it may potentially change at any time, making this tool fail or return invalid results 🤷. + +(If any of the above caveats bothers you or makes you even even more confused, please refer to https://github.com/WordPress/gutenberg/issues/35630) -Please note this simple script still has several limitations. -1. It works for WooCommerce deps only. WordPress ones are more tricky to get, as the list of packages is less static and regular. Theoretically, we should be able to [use dist-tags](https://github.com/WordPress/gutenberg/issues/24376), like `npm install @wordpress/components@wp-6.1.0` or `npx wp-scripts packages-update --dist-tag=wp-5.8`. -2. It assumes all packages are prefixed with `@woocommerce/` -3. You need to provide the exact full version. The latest, or `x.y` tree lines are not being resolved automatically. -4. Some packages externalized by DEWP, are not packages we could find neither in npm nor in [`woocommerce/woocommerce/packages/js`](https://github.com/woocommerce/woocommerce/commits/trunk/packages/js/) 🤷 -5. It requires at least Node 18 to run. diff --git a/bin/list-woo-dewped.mjs b/bin/list-woo-dewped.mjs deleted file mode 100755 index 55ea063bc6..0000000000 --- a/bin/list-woo-dewped.mjs +++ /dev/null @@ -1,65 +0,0 @@ -#!/usr/bin/env node -/* eslint-disable @woocommerce/dependency-group */ -/* global fetch */ -'use strict'; -import * as fs from 'node:fs'; - -const externalizedListPath = '.externalized.json'; -const wooPackage = ( tag, packageName ) => - `https://raw.githubusercontent.com/woocommerce/woocommerce/${ tag }/packages/js/${ packageName }/package.json`; - -const myArgs = process.argv.slice( 2 ); -const wcTag = myArgs[ 0 ]; -if ( ! wcTag || ! wcTag.match( /^(\d+).(\d+).(\d+).*/ ) ) { - // eslint-disable-next-line no-console - console.warn( - "Warning: It seems you didn't provide a valid WooCommerce tag." - ); -} - -// Warn about the needed fetch, available since Node 18+, or 17 behind the flag. -const majorNodeVersion = Number( process.versions.node.match( /^(\d+)\./ )[ 1 ] ); -if( majorNodeVersion < 18 ) { - // eslint-disable-next-line no-console - console.warn( - "Warning: Please use the Node version that supports `fetch`, like 18+." - ); -} - -const externalizedList = JSON.parse( fs.readFileSync( externalizedListPath ) ); -// Filter only packages externalized by `@woocommerce/dependency-extraction-webpack-plugin`. -const wooDependencies = externalizedList.filter( ( dependency ) => - dependency.startsWith( '@woocommerce/' ) -); -/** - * Tries to fetch the version of `@woocommerce/` package used by the given WooCommerce version. - * - * @param {string} tag Full tag name of released version, `'x.y.z'`. - * @param {string} packageName Package named to be looked up in `/packages/js/*`. - * @return {string|undefined} `'a.b.c'` version of the package, or `undefined` if not found. - */ -async function fetchVersion( tag, packageName ) { - // Strip just the name used as folder name of `/packages/js/*`. - packageName = packageName.match( /@woocommerce\/(.*)/ )[ 1 ]; - - // Read its `package.json`. - return fetch( wooPackage( tag, packageName ) ) - .then( ( response ) => response.json() ) - .then( ( packageJson ) => { - return packageJson.version; - } ) - .catch( () => { - // Most problably there is no package of that name. - return undefined; - } ); -} -// Build a Map-like array of package versions. -const versions = await Promise.all( - wooDependencies.map( async ( packageName ) => { - return [ packageName, await fetchVersion( wcTag, packageName ) ]; - } ) -); -// eslint-disable-next-line no-console -- We want to actually return something to stdout. -console.log( versions ); - -export default versions; diff --git a/package.json b/package.json index 4ff6c1730d..0786e77ede 100644 --- a/package.json +++ b/package.json @@ -94,7 +94,6 @@ "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "dev": "NODE_ENV=development wp-scripts build", - "dewps:woo": "node bin/list-woo-dewped.mjs", "doc:tracking": "woocommerce-grow-jsdoc ./js/src", "format": "wp-scripts format", "i18n": "WP_CLI_PHP_ARGS='-d memory_limit=2048M' ./vendor/bin/wp i18n make-pot ./ languages/$npm_package_name.pot --slug=$npm_package_name --domain=$npm_package_name --exclude=bin,data,js/src,node_modules,tests,vendor", @@ -106,7 +105,7 @@ "lint:php-tests": "vendor/bin/phpcs --standard=tests/phpcs.xml.dist", "lint:fix:php": "vendor/bin/phpcbf; vendor/bin/phpcbf --standard=tests/phpcs.xml.dist", "lint:pkg-json": "wp-scripts lint-pkg-json", - "outdated:dewp": "npm outdated `cat .externalized.json | sed 's/[][\",]/ /g'` || true", + "outdated:dewp": "npm outdated --color=always `cat .externalized.json | sed 's/[][\",]/ /g'` | grep -E --color=never \"Depended by|google-listings-and-ads$\" || true", "outdated:nondewp": "npm outdated --color=always | grep --color=never --invert -E \"^(.\\[31m|.\\[33m)?(`cat .externalized.json | sed 's/[][\"]//g'| sed 's/,/|/g'`)\"", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start",