From 1e4d55b36af54660769dc13a87a0b81fef242b20 Mon Sep 17 00:00:00 2001 From: Christopher Allford <6451942+ObliviousHarmony@users.noreply.github.com> Date: Fri, 17 Nov 2023 10:11:56 -0800 Subject: [PATCH] Updated Documentation --- .../non-cot-pr-build-and-e2e-tests.yml | 4 +- DEVELOPMENT.md | 49 +++++-------------- .../minification-of-SCSS-and-JS.md | 2 +- package.json | 1 + packages/js/README.md | 3 +- plugins/woo-ai/bin/build-zip.sh | 2 +- plugins/woocommerce-beta-tester/README.md | 4 +- .../woocommerce-beta-tester/bin/build-zip.sh | 2 +- plugins/woocommerce/README.md | 12 ++--- plugins/woocommerce/bin/build-zip.sh | 4 +- .../includes/class-woocommerce.php | 2 +- .../tests/api-core-tests/README.md | 2 +- plugins/woocommerce/tests/e2e-pw/README.md | 2 +- plugins/woocommerce/tests/e2e/README.md | 4 +- 14 files changed, 35 insertions(+), 58 deletions(-) diff --git a/.github/workflows/non-cot-pr-build-and-e2e-tests.yml b/.github/workflows/non-cot-pr-build-and-e2e-tests.yml index 1557bee74fd..3ed9fc4ae18 100644 --- a/.github/workflows/non-cot-pr-build-and-e2e-tests.yml +++ b/.github/workflows/non-cot-pr-build-and-e2e-tests.yml @@ -29,7 +29,7 @@ jobs: - name: Load docker images and start containers working-directory: plugins/woocommerce - run: pnpm env:test --filter=@woocommerce/plugin-woocommerce + run: pnpm --filter='@woocommerce/plugin-woocommerce' env:test - name: Download and install Chromium browser. working-directory: plugins/woocommerce @@ -87,7 +87,7 @@ jobs: - name: Load docker images and start containers working-directory: plugins/woocommerce - run: pnpm env:test --filter=@woocommerce/plugin-woocommerce + run: pnpm --filter='@woocommerce/plugin-woocommerce' env:test - name: Run Playwright API tests. id: run_playwright_api_tests diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8f7dd74d4a1..859f41fafb2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,70 +6,47 @@ This document aims to provide as much context as possible to aid in the developm Please refer to [the Getting Started section of the `README.md`](README.md#getting-started) for a general-purpose guide on getting started. The rest of this document will assume that you've installed all of the prequisites and setup described there. -## Turborepo Commands - -Our repository uses [Turborepo](https://turborepo.org) for `build` and `test` commands. This tool ensures that all dependencies of a plugin, package, or tool are prepared before running a command. This is done transparently when running these commands. When using `pnpm run {command}` without any options, it will execute that command against every project in the repository. You can view a list of the commands Turborepo supports in [our turbo.json file](turbo.json). - ### Plugin, Package, and Tool Filtering -If you are interested in running a `turbo` command against a single plugin, package, or tool, you can do so with the `--filter` flag. This flag supports the `"name"` option in `package.json` files, paths, and globs. - -If you would like to read more about the syntax, please check out [the Turborepo filtering documentation](https://turborepo.org/docs/core-concepts/filtering). +In order to run commands on individual projects you will need to utilize [PNPM's --filter flag](https://pnpm.io/filtering). This flag supports `"name"` option in `package.json`, paths, and globs. ### Examples -Here are some examples of the ways you can use Turborepo / pnpm commands: +Here are some examples of the ways you can use `pnpm` commands: ```bash -# Lint and build all plugins, packages, and tools. Note the use of `-r` for lint, -# turbo does not run the lint at this time. -pnpm run -r lint && pnpm run build +# Lint and build all plugins, packages, and tools. +pnpm lint && pnpm run build # Build WooCommerce Core and all of its dependencies -pnpm run --filter='@woocommerce/plugin-woocommerce' build +pnpm --filter='@woocommerce/plugin-woocommerce' build -# Lint the @woocommerce/components package - note the different argument order, turbo scripts -# are not running lints at this point in time. -pnpm run -r --filter='@woocommerce/components' lint +# Lint the @woocommerce/components package +pnpm --filter='@woocommerce/components' lint # Test all of the @woocommerce scoped packages -pnpm run --filter='@woocommerce/*' test +pnpm --filter='@woocommerce/*' test # Build all of the JavaScript packages -pnpm run --filter='./packages/js/*' build +pnpm --filter='./packages/js/*' build # Build everything except WooCommerce Core -pnpm run --filter='!@woocommerce/plugin-woocommerce' build +pnpm --filter='!@woocommerce/plugin-woocommerce' build # Build everything that has changed since the last commit -pnpm run --filter='[HEAD^1]' build +pnpm --filter='[HEAD^1]' build ``` -### Cache busting Turbo - -In the event that you need to force turbo not to cache a command you can set the env variable `TURBO_FORCE=true`. - -e.g. - -```bash -# Force an uncached build of WooCommerce Core and all of its dependencies -TURBO_FORCE=true pnpm run --filter='@woocommerce/plugin-woocommerce' build -``` - -## Other Commands - -Outside of the commands in [our turbo.json file](turbo.json), each plugin, package, and tool may have unique scripts in their `package.json` files. In these cases, you can execute those commands using `pnpm {script}` and the same `--filter` syntax as Turborepo. - ### Examples Here are some examples of the commands you will make use of. ```bash # Add a changelog entry for WooCommerce Core -pnpm --filter=@woocommerce/plugin-woocommerce run changelog add +pnpm --filter='@woocommerce/plugin-woocommerce' changelog add # Create the woocommerce.zip file -pnpm --filter=@woocommerce/plugin-woocommerce run build:zip +pnpm --filter='@woocommerce/plugin-woocommerce' build:zip ``` ## Plugin Development Environments diff --git a/docs/contributing/minification-of-SCSS-and-JS.md b/docs/contributing/minification-of-SCSS-and-JS.md index acf4115e7aa..2c3dde67f90 100644 --- a/docs/contributing/minification-of-SCSS-and-JS.md +++ b/docs/contributing/minification-of-SCSS-and-JS.md @@ -6,7 +6,7 @@ post_title: Minification of SCSS and JS When updating SCSS files in the WooCommerce project, please **commit only your changes to unminified SCSS files**. The minification will be handled as part of the release process. -To get the minified CSS files, run `pnpm -- turbo run build --filter='woocommerce-legacy-assets'` from the repository root directory. To set up the development environment from scratch, see the section on [how to install dependencies and generate assets](https://github.com/woocommerce/woocommerce/wiki/How-to-set-up-WooCommerce-development-environment#install-dependencies-and-generate-assets) in the guide to set up a WooCommerce development environment. +To get the minified CSS files, run `pnpm --filter='@woocommerce/shortcode-assets' build` from the repository root directory. To set up the development environment from scratch, see the section on [how to install dependencies and generate assets](https://github.com/woocommerce/woocommerce/wiki/How-to-set-up-WooCommerce-development-environment#install-dependencies-and-generate-assets) in the guide to set up a WooCommerce development environment. ## Javascript diff --git a/package.json b/package.json index f26ce051cbd..bbe07a9173a 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,7 @@ "scripts": { "build": "pnpm -r build", "test": "pnpm -r test", + "lint": "pnpm -r lint", "cherry-pick": "node ./tools/cherry-pick/bin/run", "clean": "pnpm store prune && git clean -fx **/node_modules && pnpm i", "preinstall": "npx only-allow pnpm", diff --git a/packages/js/README.md b/packages/js/README.md index 5c7dfe15136..5ad5e36e336 100644 --- a/packages/js/README.md +++ b/packages/js/README.md @@ -60,8 +60,7 @@ To create a new package, add a new folder to `/packages`, containing… - Package description - Installation details - Usage example -4. A `src` directory for the source of your module, which will be built by default using the `pnpm run turbo:build` command. Note that you'll want an `index.js` file that exports the package contents, see other packages for examples. - +4. A `src` directory for the source of your module. Note that you'll want an `index.js` file that exports the package contents, see other packages for examples. 5. A blank Changelog file, `changelog.md`. ``` diff --git a/plugins/woo-ai/bin/build-zip.sh b/plugins/woo-ai/bin/build-zip.sh index 98c707e48fa..b3c3a8334c9 100755 --- a/plugins/woo-ai/bin/build-zip.sh +++ b/plugins/woo-ai/bin/build-zip.sh @@ -12,7 +12,7 @@ mkdir -p "$DEST_PATH" echo "Installing PHP and JS dependencies..." pnpm install echo "Running JS Build..." -pnpm -w run build --filter=@woocommerce/plugin-woo-ai || exit "$?" +pnpm --filter='@woocommerce/plugin-woo-ai' build || exit "$?" echo "Syncing files..." rsync -rc --exclude-from="$PROJECT_PATH/.distignore" "$PROJECT_PATH/" "$DEST_PATH/" --delete --delete-excluded diff --git a/plugins/woocommerce-beta-tester/README.md b/plugins/woocommerce-beta-tester/README.md index 65a1889ebfb..5af12e07e16 100644 --- a/plugins/woocommerce-beta-tester/README.md +++ b/plugins/woocommerce-beta-tester/README.md @@ -11,8 +11,8 @@ You can either install the latest version from [wp.org](https://wordpress.org/pl To get started, run the following commands: ```text -pnpm install -pnpm run start +pnpm --filter=@woocommerce/plugin-woocommerce-beta-tester install +pnpm --filter=@woocommerce/plugin-woocommerce-beta-tester run start ``` See [wp-scripts](https://github.com/WordPress/gutenberg/tree/master/packages/scripts) for more usage information. diff --git a/plugins/woocommerce-beta-tester/bin/build-zip.sh b/plugins/woocommerce-beta-tester/bin/build-zip.sh index 3207098d7a7..bfc53ef34bb 100755 --- a/plugins/woocommerce-beta-tester/bin/build-zip.sh +++ b/plugins/woocommerce-beta-tester/bin/build-zip.sh @@ -12,7 +12,7 @@ mkdir -p "$DEST_PATH" echo "Installing PHP and JS dependencies..." pnpm install echo "Running JS Build..." -pnpm -w run build --filter=@woocommerce/plugin-woocommerce-beta-tester || exit "$?" +pnpm --filter='@woocommerce/plugin-woocommerce-beta-tester' build || exit "$?" echo "Syncing files..." rsync -rc --exclude-from="$PROJECT_PATH/.distignore" "$PROJECT_PATH/" "$DEST_PATH/" --delete --delete-excluded diff --git a/plugins/woocommerce/README.md b/plugins/woocommerce/README.md index 05dd9b65f45..8d574308bff 100644 --- a/plugins/woocommerce/README.md +++ b/plugins/woocommerce/README.md @@ -16,7 +16,7 @@ Please make sure you follow the [repository's getting started guide](../../READM ```bash # Make sure that WooCommerce Core and all of its dependencies are built -pnpm run --filter=@woocommerce/plugin-woocommerce build +pnpm --filter=@woocommerce/plugin-woocommerce build # Make sure you're in the WooCommerce Core directory cd plugins/woocommerce # Start the development environment @@ -36,9 +36,9 @@ This directory contains the CSS and jQuery code for WooCommerce shortcodes. ```bash # Build the assets. -pnpm run --filter=@woocommerce/shortcode-assets build +pnpm --filter=@woocommerce/shortcode-assets build # Lint the assets. -pnpm run --filter=@woocommerce/shortcode-assets lint +pnpm --filter=@woocommerce/shortcode-assets lint ``` ### `plugins/woocommerce-admin` @@ -47,11 +47,11 @@ This directory contains the React-based admin interface. ```bash # Build the React-based admin client. -pnpm run --filter=@woocommerce/admin-library build +pnpm --filter=@woocommerce/admin-library build # Lint the React-based admin client. -pnpm run --filter=@woocommerce/admin-library lint +pnpm --filter=@woocommerce/admin-library lint # Test the React-based admin client. -pnpm run --filter=@woocommerce/admin-library test +pnpm --filter=@woocommerce/admin-library test ``` #### Helper Scripts diff --git a/plugins/woocommerce/bin/build-zip.sh b/plugins/woocommerce/bin/build-zip.sh index 0d65485d714..2b8fc30b0e6 100755 --- a/plugins/woocommerce/bin/build-zip.sh +++ b/plugins/woocommerce/bin/build-zip.sh @@ -15,11 +15,11 @@ find "$PROJECT_PATH/assets/css/." ! -name '.gitkeep' -type f -exec rm -f {} + && echo "Installing PHP and JS dependencies..." pnpm install echo "Running JS Build..." -pnpm -w run build --filter=@woocommerce/plugin-woocommerce || exit "$?" +pnpm --filter='@woocommerce/plugin-woocommerce' build || exit "$?" echo "Cleaning up PHP dependencies..." composer install --no-dev || exit "$?" echo "Run makepot..." -pnpm -r --filter=@woocommerce/plugin-woocommerce run makepot || exit "$?" +pnpm --filter=@woocommerce/plugin-woocommerce makepot || exit "$?" echo "Syncing files..." rsync -rc --exclude-from="$PROJECT_PATH/.distignore" "$PROJECT_PATH/" "$DEST_PATH/" --delete --delete-excluded diff --git a/plugins/woocommerce/includes/class-woocommerce.php b/plugins/woocommerce/includes/class-woocommerce.php index 719af0e1d19..fa4943a2e70 100644 --- a/plugins/woocommerce/includes/class-woocommerce.php +++ b/plugins/woocommerce/includes/class-woocommerce.php @@ -1028,7 +1028,7 @@ final class WooCommerce { return; } - $message_one = __( 'You have installed a development version of WooCommerce which requires files to be built and minified. From the plugin directory, run pnpm install and then pnpm run build --filter=@woocommerce/plugin-woocommerce to build and minify assets.', 'woocommerce' ); + $message_one = __( 'You have installed a development version of WooCommerce which requires files to be built and minified. From the plugin directory, run pnpm install and then pnpm --filter=\'@woocommerce/plugin-woocommerce\' build to build and minify assets.', 'woocommerce' ); $message_two = sprintf( /* translators: 1: URL of WordPress.org Repository 2: URL of the GitHub Repository release page */ __( 'Or you can download a pre-built version of the plugin from the WordPress.org repository or by visiting the releases page in the GitHub repository.', 'woocommerce' ), diff --git a/plugins/woocommerce/tests/api-core-tests/README.md b/plugins/woocommerce/tests/api-core-tests/README.md index f43b75ebeee..b26220270f4 100644 --- a/plugins/woocommerce/tests/api-core-tests/README.md +++ b/plugins/woocommerce/tests/api-core-tests/README.md @@ -38,7 +38,7 @@ WooCommerce's `api-core-tests` are powered by Playwright. The test site is spun - `nvm use` - `pnpm install` -- `pnpm run build --filter=@woocommerce/plugin-woocommerce` +- `pnpm --filter='@woocommerce/plugin-woocommerce' build` - `cd plugins/woocommerce` - `pnpm env:test` - `pnpm test:api-pw` diff --git a/plugins/woocommerce/tests/e2e-pw/README.md b/plugins/woocommerce/tests/e2e-pw/README.md index 469c76538c4..e92ecdaa6a4 100644 --- a/plugins/woocommerce/tests/e2e-pw/README.md +++ b/plugins/woocommerce/tests/e2e-pw/README.md @@ -36,7 +36,7 @@ End-to-end tests are powered by Playwright. The test site is spinned up using `w - `nvm use` (uses the default node version you have set in NVM) - `pnpm install` (installs dependencies) -- `pnpm run build --filter=@woocommerce/plugin-woocommerce` (builds WooCommerce locally) +- `pnpm --filter='@woocommerce/plugin-woocommerce' build` (builds WooCommerce locally) - `cd plugins/woocommerce` (changes into the WooCommerce plugin folder) - `npx playwright install` (installs the latest Playwright version) - `pnpm env:start` (starts the local environment) diff --git a/plugins/woocommerce/tests/e2e/README.md b/plugins/woocommerce/tests/e2e/README.md index 1f70c074cdc..9fb50c76fb5 100644 --- a/plugins/woocommerce/tests/e2e/README.md +++ b/plugins/woocommerce/tests/e2e/README.md @@ -120,11 +120,11 @@ Run the following in a terminal/command line window - `pnpm install` -- `pnpm run build --filter=@woocommerce/plugin-woocommerce` +- `pnpm --filter='@woocommerce/plugin-woocommerce' build` - `npm install jest --global` (this only needs to be done once) -- `pnpm docker:up --filter=@woocommerce/plugin-woocommerce` (this will build the test site using Docker) +- `pnpm --filter='@woocommerce/plugin-woocommerce' docker:up` (this will build the test site using Docker) - Use `docker ps` to confirm that the Docker containers are running. You should see a log similar to one below indicating that everything had been built as expected: