mirror of
https://github.com/woocommerce/woocommerce.git
synced 2025-08-18 10:21:16 +08:00
Document Monorepo Script Structure (#51820)
* Clarified Monorepo Setup Instructions * Documented Monorepo Architecture * Linting Fix * Documentation: note about dev-environments. * Documentation: note about dev-environments. * Documentation: clarity on supported environments. * Documentation: clarification on build command. * Documentation: cleanup. * Documentation: cleanup. * Documentation: code review feedback. * Documentation: cleanup. * Documentation: cleanup. * Documentation: cleanup. * Documentation: changelog entry. * Documentation: code review feedback. * Documentation: code review feedback. * Documentation: fix md-linting violation. * Documentation: fix md-linting violation. * Update plugins/woocommerce/README.md Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com> * Update tools/README.md Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com> * Update tools/README.md Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com> --------- Co-authored-by: Vladimir Reznichenko <kalessil@gmail.com> Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com>
This commit is contained in:
Christopher Allford
GitHub
parent
23e3c066a3
commit
1ec468d1d7
4 changed files with 114 additions and 41 deletions
10
README.md
10
README.md
|
|
@ -17,7 +17,7 @@ To get up and running within the WooCommerce Monorepo, you will need to make sur
|
|||
- [PHP 7.4+](https://www.php.net/manual/en/install.php): WooCommerce Core currently features a minimum PHP version of 7.4. It is also needed to run Composer and various project build scripts. See [troubleshooting](DEVELOPMENT.md#troubleshooting) for troubleshooting problems installing PHP.
|
||||
- [Composer](https://getcomposer.org/doc/00-intro.md): We use Composer to manage all of the dependencies for PHP packages and plugins.
|
||||
|
||||
Once you've installed all of the prerequisites, you can run the following commands to get everything working.
|
||||
Once you've installed all of the prerequisites, the following will prepare all of the build outputs necessary for development:
|
||||
|
||||
```bash
|
||||
# Ensure that correct version of Node is installed and being used
|
||||
|
|
@ -28,17 +28,17 @@ pnpm install
|
|||
pnpm build
|
||||
```
|
||||
|
||||
At this point you are now ready to begin developing and testing. All of the build outputs are cached running `pnpm build` again will only build the plugins, packages, and tools that have changed since the last time you ran the command.
|
||||
|
||||
Check out [our development guide](DEVELOPMENT.md) if you would like a more comprehensive look at working in our repository.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
Each plugin, package, and tool has its own `package.json` file containing project-specific dependencies and scripts. Most projects also contain a `README.md` file with any project-specific setup instructions and documentation.
|
||||
|
||||
- [**Plugins**](plugins): Our repository contains plugins that relate to or otherwise aid in the development of WooCommerce.
|
||||
- [**WooCommerce Core**](plugins/woocommerce): The core WooCommerce plugin is available in the plugins directory.
|
||||
- [**Packages**](packages): Contained within the packages directory are all of the [PHP](packages/php) and [JavaScript](packages/js) provided for the community. Some of these are internal dependencies and are marked with an `internal-` prefix.
|
||||
- [**Tools**](tools): We also have a growing number of tools within our repository. Many of these are intended to be utilities and scripts for use in the monorepo, but, this directory may also contain external tools.
|
||||
|
||||
If you'd like to learn more about how our monorepo works, [please check out this guide here](tools/README.md).
|
||||
|
||||
## Reporting Security Issues
|
||||
|
||||
To disclose a security issue to our team, [please submit a report via HackerOne here](https://hackerone.com/automattic/).
|
||||
|
|
|
|||
|
|
@ -12,22 +12,28 @@ If you are not a developer, please use the [WooCommerce plugin page](https://wor
|
|||
|
||||
## Getting Started
|
||||
|
||||
Please make sure you follow the [repository's getting started guide](../../README.md#getting-started) first!
|
||||
### Quick start
|
||||
|
||||
Ensure your system meets [the requirements](../../README.md#getting-started) (TLDR: NVM, PNPM 9.1.3, PHP 7.4+, Composer are required for development).
|
||||
|
||||
Depending on the preferred environment for running the development instance of WooCommerce, you might need [Docker](https://docs.docker.com/get-docker/) as well. You can learn more about supported environments [here](https://developer.woocommerce.com/docs/setting-up-your-development-environment/).
|
||||
|
||||
Once you have verified the prerequisites, you can start the development environment:
|
||||
|
||||
```bash
|
||||
# Make sure that WooCommerce Core and all of its dependencies are built
|
||||
pnpm --filter=@woocommerce/plugin-woocommerce build
|
||||
# Make sure you're in the WooCommerce Core directory
|
||||
cd plugins/woocommerce
|
||||
# Start the development environment
|
||||
pnpm -- wp-env start
|
||||
## Watch for changes in WooCommerce and all of its dependencies.
|
||||
pnpm --filter='@woocommerce/plugin-woocommerce' watch:build
|
||||
|
||||
# Start a wp-env based development environment, which will be accessible via http://localhost:8888/.
|
||||
# This step is optional and you can skip it if you are running WooCommerce on a custom setup.
|
||||
pnpm --filter='@woocommerce/plugin-woocommerce' env:dev
|
||||
```
|
||||
|
||||
You should now be able to visit `http://localhost:8888/` and access WooCommerce environment.
|
||||
If desired, you can also run commands without `--filter='@woocommrece/plugin-woocommerce'` by running `pnpm <command>` from within the `plugins/woocommerce` directory.
|
||||
|
||||
## Building Components
|
||||
|
||||
There are two major client-side components included in WooCommerce Core that can be built, linted, and tested independently. We've organized these components
|
||||
There are three major client-side components included in WooCommerce Core that can be built, linted, and tested independently. We've organized these components
|
||||
in this way to take advantage of caching to prevent unnecessarily performing expensive rebuilds when only working in one of them.
|
||||
|
||||
### `plugins/woocommerce/client/legacy`
|
||||
|
|
@ -36,9 +42,9 @@ This directory contains the Classic CSS and jQuery code for WooCommerce.
|
|||
|
||||
```bash
|
||||
# Build the assets.
|
||||
pnpm --filter=@woocommerce/classic-assets build
|
||||
pnpm --filter='@woocommerce/plugin-woocommerce' build:classic-assets
|
||||
# Lint the assets.
|
||||
pnpm --filter=@woocommerce/classic-assets lint
|
||||
pnpm --filter='@woocommerce/classic-assets' lint
|
||||
```
|
||||
|
||||
### `plugins/woocommerce/client/admin`
|
||||
|
|
@ -47,11 +53,15 @@ This directory contains the React-based admin interface.
|
|||
|
||||
```bash
|
||||
# Build the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library build
|
||||
pnpm --filter='@woocommerce/plugin-woocommerce' build:admin
|
||||
# Lint the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library lint
|
||||
pnpm --filter='@woocommerce/admin-library' lint
|
||||
# Test the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library test
|
||||
pnpm --filter='@woocommerce/admin-library' test
|
||||
# Watch the tests of the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library test:watch
|
||||
# Run a type check over the React-based admin client's TypeScript files.
|
||||
pnpm --filter=@woocommerce/admin-library ts:check
|
||||
```
|
||||
|
||||
### `plugins/woocommerce-blocks`
|
||||
|
|
@ -60,34 +70,19 @@ This directory contains the client for WooCommerce + Gutenberg.
|
|||
|
||||
```bash
|
||||
# Build the Blocks client.
|
||||
pnpm run --filter=@woocommerce/block-library build
|
||||
pnpm --filter='@woocommerce/plugin-woocommerce' build:blocks
|
||||
# Lint the Blocks client.
|
||||
pnpm run --filter=@woocommerce/block-library lint
|
||||
pnpm run --filter='@woocommerce/block-library' lint
|
||||
# Test the Blocks client.
|
||||
pnpm run --filter=@woocommerce/block-library test
|
||||
```
|
||||
|
||||
#### Helper Scripts
|
||||
|
||||
Here is a collection of scripts that can help when developing the React-based admin interface.
|
||||
|
||||
```bash
|
||||
# Create a development build of the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library dev
|
||||
# Create and watch a development build of the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library start
|
||||
# Watch the tests of the React-based admin client.
|
||||
pnpm --filter=@woocommerce/admin-library test:watch
|
||||
# Run a type check over the React-based admin client's TypeScript files.
|
||||
pnpm --filter=@woocommerce/admin-library ts:check
|
||||
pnpm run --filter='@woocommerce/block-library' test
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
* [WooCommerce Documentation](https://woocommerce.com/)
|
||||
* [WooCommerce Developer Documentation](https://github.com/woocommerce/woocommerce/wiki)
|
||||
* [WooCommerce Code Reference](https://woocommerce.com/wc-apidocs/)
|
||||
* [WooCommerce REST API Docs](https://woocommerce.github.io/woocommerce-rest-api-docs/)
|
||||
- [WooCommerce Documentation](https://woocommerce.com/)
|
||||
- [WooCommerce Developer Documentation](https://github.com/woocommerce/woocommerce/wiki)
|
||||
- [WooCommerce Code Reference](https://woocommerce.com/wc-apidocs/)
|
||||
- [WooCommerce REST API Docs](https://woocommerce.github.io/woocommerce-rest-api-docs/)
|
||||
|
||||
## Reporting Security Issues
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
Significance: patch
|
||||
Type: dev
|
||||
|
||||
Monorepo: developers documentation update.
|
||||
74
tools/README.md
Normal file
74
tools/README.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# Monorepo Infrastructure & Tools
|
||||
|
||||
This document aims to provide an outline for the monorepo's infrastructure as well as the rationale behind the decisions we've made.
|
||||
|
||||
## Task Orchestration
|
||||
|
||||
Our repository makes aggressive use of [parallelization using PNPM's `--filter` syntax](https://pnpm.io/filtering). This allows us to minimize the amount of time developers spend waiting for tasks like builds to complete. Each project within the monorepo will contain the following scripts if applicable:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build": "pnpm --if-present --workspace-concurrency=Infinity --stream --filter=\"$npm_package_name...\" '/^build:project:.*$/'",
|
||||
"build:project": "pnpm --if-present '/^build:project:.*$/'",
|
||||
"lint": "pnpm --if-present '/^lint:lang:.*$/'",
|
||||
"lint:fix": "pnpm --if-present '/^lint:fix:lang:.*$/'",
|
||||
"watch:build": "pnpm --if-present --workspace-concurrency=Infinity --filter=\"$npm_package_name...\" --parallel '/^watch:build:project:.*$/'",
|
||||
"watch:build:project": "pnpm --if-present run '/^watch:build:project:.*$/'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
These scripts outline the naming scheme used in order to facilitate [task parallelization using regular expressions](https://pnpm.io/cli/run#running-multiple-scripts). **To ensure consistency across the monorepo, these scripts should not be edited.** New scripts should be added using the naming scheme outlined by the above regular expressions, for example, `build:project:bundle` might be a script to run a tool like `webpack`. We also utilize a number of PNPM options to ensure a positive developer experience:
|
||||
|
||||
- `--if-present`: Ensures that PNPM will not error if a script is not found.
|
||||
- `--workspace-concurrency=Infinity`: Runs as many of the tasks in parallel as possible.
|
||||
- `--stream`: Makes the script output legible by putting all of their output into a single stream.
|
||||
- `--filter="$npm_package_name..."`: This filter tells PNPM that we want to run the script against the current project _and_ all of its dependencies down the graph (dependencies first).
|
||||
|
||||
To further improve the build times, we used two additional techniques:
|
||||
|
||||
- In the case of the `build` script, we offer both building packages with (`build`) and without (`build:project`) its dependencies.
|
||||
- Using `wireit`-based task output caching (details are below).
|
||||
|
||||
## Task Output Caching
|
||||
|
||||
Our repository uses [`wireit`](https://github.com/google/wireit) to provide task output caching. In particular, this allows us to cache the output of `build` scripts so that they don't run unnecessarily.
|
||||
The goal is to minimize the amount of time that developers spend waiting for projects to build.
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build": "pnpm --if-present --workspace-concurrency=Infinity --stream --filter=\"$npm_package_name...\" '/^build:project:.*$/'",
|
||||
"build:project": "pnpm --if-present '/^build:project:.*$/'",
|
||||
"build:project:bundle": "wireit"
|
||||
},
|
||||
"wireit": {
|
||||
"build:project:bundle": {
|
||||
"command": "webpack",
|
||||
"files": [
|
||||
"... - package resources as input"
|
||||
],
|
||||
"output": [
|
||||
"... - package resources as output"
|
||||
],
|
||||
"dependencies": [
|
||||
"dependencyOutputs"
|
||||
]
|
||||
},
|
||||
"dependencyOutputs": {
|
||||
"files": [
|
||||
"... - dependencies resources as input",
|
||||
"... - updated automatically by monorepo tooling which hooks up into `pnpm install`",
|
||||
"... - see `.pnpmfile.cjs` file and https://pnpm.io/pnpmfile for details"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example above, `build:project:bundle` invokes `wireit`, which conditionally executes `webpack` (based on the state of resources).
|
||||
A simplified take on `wireit` is the following:
|
||||
|
||||
- if input sources are changed or output sources are not generated yet, `wireit` will execute `webpack` command and cache output sources
|
||||
- if input sources are unchanged, `wireit` will create output sources from their cached version
|
||||
Loading…
Add table
Add a link
Reference in a new issue
