Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Expand Repository Development Documentation (#33423) 

This commit reworks some of the documentation in the monorepo to better represent how to get started and develop projects in it.
This commit is contained in:
Christopher Allford 2022-06-15 21:55:25 -07:00 committed by GitHub
parent b79e54eb09
commit 6d0fc0d6ac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 394 additions and 296 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/actions/install-build/action.yml vendored
View File

@ -22,4 +22,4 @@ runs:
- name: Run build
shell: bash
working-directory: ${{ inputs.working_directory }}
run: pnpm exec turbo run build --filter=woocommerce
run: pnpm -- turbo run build --filter=woocommerce

2
.github/workflows/ci.yml vendored
View File

@ -83,4 +83,4 @@ jobs:
run: ./tests/bin/install.sh woo_test root root 127.0.0.1 ${{ matrix.wp }}
- name: Run tests
run: pnpm exec turbo run test --filter=woocommerce
run: pnpm -- turbo run test --filter=woocommerce

4
.github/workflows/pr-lint-test-js.yml vendored
View File

@ -35,7 +35,7 @@ jobs:
uses: ./.github/actions/install-build
- name: Lint
run: pnpm exec turbo run lint --filter='@woocommerce/admin-library...' --filter='!@woocommerce/e2e*' --filter='!@woocommerce/api'
run: pnpm -- turbo run lint --filter='@woocommerce/admin-library...' --filter='!@woocommerce/e2e*' --filter='!@woocommerce/api'
- name: Test
run: pnpm exec turbo run test --filter='@woocommerce/admin-library...' --filter='!@woocommerce/e2e*' --filter='!@woocommerce/api'
run: pnpm -- turbo run test --filter='@woocommerce/admin-library...' --filter='!@woocommerce/e2e*' --filter='!@woocommerce/api'

2
.github/workflows/pr-unit-tests.yml vendored
View File

@ -80,4 +80,4 @@ jobs:
run: ./tests/bin/install.sh woo_test root root 127.0.0.1 ${{ matrix.wp }}
- name: Run tests
run: pnpm exec turbo run test --filter=woocommerce
run: pnpm -- turbo run test --filter=woocommerce

160
DEVELOPMENT.md
View File

@ -1,131 +1,79 @@
# WooCommerce Development Setup with WP-ENV
# Development
Docker development setup for WooCommerce with WP-ENV.
This document aims to provide as much context as possible to aid in the development of plugins, packages, and tools in the monorepo.
## Prerequisites
## Getting Started
Please install WP-ENV before getting started. You can find more about WP-ENV on [here](https://github.com/WordPress/gutenberg/tree/master/packages/env).
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.
The following command installs WP-ENV globally.
## Turborepo Commands
`npm -g i @wordpress/env`
Our repository uses [Turborepo](https://turborepo.org) for `build`, `lint`, and `test` commands. This tool ensures that all dependencies of a plugin, package, or tool are prepared before running a command. When using `pnpm -- turbo 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).
If you don't already have [pnpm](https://pnpm.io/installation) installed, you can quickly add it using NPM.
### Plugin, Package, and Tool Filtering
`npm install -g pnpm@^6.24.2`
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.
## Starting WP-ENV
If you would like to read more about the syntax, please check out [the Turborepo filtering documentation](https://turborepo.org/docs/core-concepts/filtering).
1. Navigate to the root of WooCommerce source code.
2. Start the docker container by running `wp-env start`
### Examples
You should see the following output
Here are some examples of the ways you can use Turborepo commands:
```
WordPress development site started at http://localhost:8888/
WordPress test site started at http://localhost:8889/
MySQL is listening on port 55003
```bash
# Lint and build all plugins, packages, and tools
pnpm -- turbo run lint build
# Build WooCommerce Core and all of its dependencies
pnpm -- turbo run build --filter='woocommerce'
# Lint the @woocommerce/components package
pnpm -- turbo run lint --filter='@woocommerce/components'
# Test all of the @woocommerce scoped packages
pnpm -- turbo run test --filter='@woocommerce/*'
# Build all of the JavaScript packages
pnpm -- turbo run build --filter='./packages/js/*'
# Build everything except WooCommerce Core
pnpm -- turbo run build --filter='!woocommerce'
# Lint everything that has changed since the last commit
pnpm -- turbo run build --filter='[HEAD^1]'
```
The port # might be different depending on your `.wp-env.override.json` configuration.
## Other Commands
## Getting Started with Developing
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.
Once you have WP-ENV container up, we need to run a few commands to start developing.
### Examples
1. Run `pnpm install` to install npm modules.
2. Run `pnpm exec turbo run build --filter=woocommerce` to build core.
Here are some examples of the commands you will make use of.
You're now ready to develop!
```bash
# Add a changelog entry for WooCommerce Core
pnpm changelog add --filter=woocommerce
### Typescript Checking
Typescript is progressively being implemented in this repository, and you might come across some files that are `.ts` or `.tsx`. By default, a VSCode environment will run type checking on such files that are currently open.
As of now, some parts of the codebase that were imported from the Woocommerce-Admin repository, into the `plugins/woocommerce-admin/client` directory, still fail Typescript checking. This has been scheduled on the team's backlog to be fixed.
In order to run type checking across the entire repository, you can run this command in your shell, from the root of this repository:
```sh
pnpm tsc -b tsconfig.base.json
# Create the woocommerce.zip file
pnpm build:zip --filter=woocommerce
```
For better developer experience, the folder `.vscode/tasks.json` has two VSCode tasks to run these commands automatically as well as to parse the output and highlight the errors in the `Problems` tab and in the file explorer pane. The first task runs it once, the second one runs it in the background upon saving of any modified files. This task is also automatically prompted by VSCode to be run upon opening the folder.
## Plugin Development Environments
The plugins in our repository make use of [the `@wordpress/env` package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). This supplies convenient commands for creating, destroying, cleaning, and testing WordPress environments.
## Using Xdebug
Please refer to [WP-ENV official README](https://github.com/WordPress/gutenberg/tree/master/packages/env#using-xdebug) section for setting up Xdebug.
## Overriding the Default Configuration
The default configuration comes with PHP 7.4, WooCommerce 5.0, and a few WordPress config values.
You can create `.wp-env.override.json` file and override the default configuration values.
You can find more about `.wp-env.override.json` configuration [here](https://github.com/WordPress/gutenberg/tree/master/packages/env#wp-envoverridejson).
**Example: Overriding PHP version to 8.0**
Create `.wp-env.override.json` in the root directory with the following content.
```json
{
"phpVersion": "8.0"
}
```bash
# Make sure you are in the working directory of the plugin you are interested in setting up the environment for
cd plugins/woocommerce
# Start will create the environment if necessary or start an existing one
pnpm -- wp-env start
# Stop will, well, stop the environment
pnpm -- wp-env stop
# Destroy will remove all of the environment's files.
pnpm -- wp-env destroy
```
**Exampe: Adding a locally installed plugin**
Each of the [plugins in our repository](plugins) support using this tool to spin up a development environment. Note that rather than having a single top-level environment, each plugin has its own. This is done in order to prevent conflicts between them.
Method 1 - Adding to the `plugins` array
Open the default `.wp-env.json` and copy `plugins` array and paste it into the `.wp-env.override.json` and add your locally installed plugin. Copying the default `plugins` is needed as WP-ENV does not merge the values of the `plugins`.
```json
{
"plugins": [
"./plugins/woocommerce",
"https://downloads.wordpress.org/plugin/wp-crontrol.1.10.0.zip"
]
}
```
Method 2 - Adding to the `mappings`
This method is simpler, but the plugin does not get activated on startup. You need to manually activate it yourself on the first startup.
```json
{
"mappings": {
"wp-content/plugins/wp-crontrol": "../woocommerce"
}
}
```
## Accessing MySQL
The MySQL port can change when you restart your container.
You can get the current MySQL port from the output of `wp-env start` command.
1. Open your choice of MySQL tool.
2. Use the following values to access the MySQL container.
| Name | Value |
| -------- | --------------------- |
| Host | 127.0.0.1 |
| Username | root |
| Password | password |
| Port | Port from the command |
## HOWTOs
##### How do I ssh into the container?
Run the following command to ssh into the container
`wp-env run wordpress /bin/bash`
You can run a command in the container with the following syntax. You can find more about on the `run` command [here](https://github.com/WordPress/gutenberg/tree/master/packages/env#wp-env-run-container-command)
Syntax:
`wp-env run :container-type :linux-command`
Please check out [the official documentation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) if you would like to learn more about this tool.

38
README.md
View File

@ -1,16 +1,9 @@
<p align="center"><a href="https://woocommerce.com/"><img src="https://woocommerce.com/wp-content/themes/woo/images/logo-woocommerce@2x.png" alt="WooCommerce"></a></p>
Welcome to the WooCommerce Monorepo on GitHub. Here you can find all of the packages, plugins, and tools used in the development of the core WooCommerce plugin as well as WooCommerce extensions. You can browse the source, look at open issues, contribute code, and keep tracking of ongoing development.
Welcome to the WooCommerce Monorepo on GitHub. Here you can find all of the plugins, packages, and tools used in the development of the core WooCommerce plugin as well as WooCommerce extensions. You can browse the source, look at open issues, contribute code, and keep tracking of ongoing development.
We recommend all developers to follow the [WooCommerce development blog](https://woocommerce.wordpress.com/) to stay up to date about everything happening in the project. You can also [follow @DevelopWC](https://twitter.com/DevelopWC) on Twitter for the latest development updates.
## Repository Structure
* [**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.
## Getting Started
To get up and running within the WooCommerce Monorepo, you will need to make sure that you have installed all of the prerequisites.
@ -22,34 +15,27 @@ To get up and running within the WooCommerce Monorepo, you will need to make sur
* [PHP 7.2+](https://www.php.net/manual/en/install.php): WooCommerce Core currently features a minimum PHP version of 7.2. While you don't need to use it to run a local development environment, you will need it to utilize Composer.
* [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.
Once you've installed all of the prerequisites, you can run the following commands to get everything working.
```bash
# Ensure that you're using the correct version of Node
nvm use
# Install all of the NPM and Composer dependencies within the Monorepo
# Install the PHP and Composer dependencies for all of the plugins, packages, and tools
pnpm install
# Build all of the plugins, packages, and tools in the monorepo
pnpm -- turbo run build
```
### Building, Linting, and Testing
At this point you are now ready to begin developing and testing. All of the build outputs are cached running `pnpm -- turbo run build` again will only build the plugins, packages, and tools that have changed since the last time you ran the command.
Our repository uses [Turborepo](https://turborepo.org) for running `build`, `lint`, `test`, and `e2e` commands. This tool ensures that all dependencies of a package, plugin, or tool are prepared before running a command. It also provides caching for command outputs in order to ensure that work is not performed unnecessarily.
Check out [our development guide](DEVELOPMENT.md) if you would like a more comprehensive look at working in our repository.
Without any additional flags, running a command will execute it against every project in the monorepo. For example, `pnpm exec turbo run build` will build all of the projects within the monorepo. `pnpm exec turbo run test` will run unit tests for all of the projects within the monorepo.
## Repository Structure
This behavior can be desireable, as the cache should ensure anything that has not changed is not rebuilt. There are times, however, that you may want to explicitly run a command against a specific project.
This can be done using the `--filter` flag. For example, running `pnpm exec turbo run build --filter=woocommerce` will build the WooCommerce plugin, as well as all of the dependencies required for the plugin to function.
The `--filter` syntax also supports paths, such as `--filter='./plugins/**'` to build all of the plugins in the monorepo. [You can read more about the filtering syntax in Turborepo's documentation](https://turborepo.org/docs/core-concepts/filtering).
### Project-Specific Commands
Outside of the above `turbo` commands, there may be times where you want to run a command on a specific project. This can _also_ be done using the `--filter` syntax, however, you will run these commands using `pnpm`. For example, `pnpm postinstall --filter=woocommerce` will run the `"postinstall"` script from `plugins/woocommerce/package.json`.
## Development Environments
Our repository makes use of [the `@wordpress/env` package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) for providing development environments out-of-the-box. Once you have installed the package and its related dependencies, you should be able to run `wp-env start` in any of the `plugins/` folders. This will start a development environment and provide you with a URL to begin testing code using.
* [**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.
## Reporting Security Issues
To disclose a security issue to our team, [please submit a report via HackerOne here](https://hackerone.com/automattic/).

2
package.json
View File

@ -65,7 +65,7 @@
"request": "^2.88.2",
"sass": "^1.49.9",
"sass-loader": "^10.2.1",
"turbo": "^1.2.9",
"turbo": "^1.2.16",
"typescript": "4.2.4",
"url-loader": "^1.1.2",
"webpack": "^5.70.0"

2
packages/js/e2e-environment/external.md
View File

@ -38,7 +38,7 @@ Again, if you don't have shell access to your test site, through WP Admin ensure
3. You have an admin user set up (if their credentials differ from u/ `admin` and p/ `password` be sure to update `/plugins/woocommerce/tests/e2e/config/default.json`)
4. You have a customer user set up named 'Jane Smith'. This user should be a `subscriber` and again make sure their username and password are reflected in `/plugins/woocommerce/tests/e2e/config/default.json`.
You should then be able to run the e2e tests by running `pnpm exec turbo run e2e --filter=woocommerce`.
You should then be able to run the e2e tests by running `pnpm -- turbo run e2e --filter=woocommerce`.
### Test Sequencer Setup

1
plugins/woocommerce-beta-tester/package.json
View File

@ -15,6 +15,7 @@
"devDependencies": {
"@woocommerce/dependency-extraction-webpack-plugin": "workspace:*",
"@woocommerce/eslint-plugin": "workspace:*",
"@wordpress/env": "^4.8.0",
"@wordpress/scripts": "^19.2.4",
"eslint": "5.16.0",
"uglify-js": "^3.5.3"

15
plugins/woocommerce/README.md
View File

@ -13,6 +13,21 @@ This is the WooCommerce Core plugin. Here you can browse the source and keep tra
If you are not a developer, please use the [WooCommerce plugin page](https://wordpress.org/plugins/woocommerce/) on WordPress.org.
## Getting Started
Please make sure you follow the [repository's getting started guide](../../README.md#getting-started) first!
```bash
# Make sure that WooCommerce Core and all of its dependencies are built
pnpm -- turbo run build --filter=woocommerce
# Make sure you're in the WooCommerce Core directory
cd plugins/woocommerce
# Start the development environment
pnpm -- wp-env start
```
You should now be able to visit http://docker.local:8888/ and access WooCommerce environment.
## Documentation
* [WooCommerce Documentation](https://docs.woocommerce.com/)
* [WooCommerce Developer Documentation](https://github.com/woocommerce/woocommerce/wiki)

2
plugins/woocommerce/bin/build-zip.sh
View File

@ -12,7 +12,7 @@ mkdir -p "$DEST_PATH"
echo "Installing PHP and JS dependencies..."
pnpm install
echo "Running JS Build..."
pnpm exec turbo run build --filter=woocommerce || exit "$?"
pnpm -w exec turbo run build --filter=woocommerce || exit "$?"
echo "Cleaning up PHP dependencies..."
composer install --no-dev || exit "$?"
echo "Run makepot..."

5
plugins/woocommerce/changelog/docs-turbo-update Normal file
View File

@ -0,0 +1,5 @@
Significance: patch
Type: dev
Comment: Updating documentation

2
plugins/woocommerce/includes/class-woocommerce.php
View File

@ -971,7 +971,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 <code>pnpm install</code> and then <code>pnpm exec turbo run build --filter=woocommerce</code> 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 <code>pnpm install</code> and then <code>pnpm -- turbo run build --filter=woocommerce</code> 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 <a href="%1$s">WordPress.org repository</a> or by visiting <a href="%2$s">the releases page in the GitHub repository</a>.', 'woocommerce' ),

1
plugins/woocommerce/package.json
View File

@ -56,6 +56,7 @@
"@woocommerce/woocommerce-rest-api": "^1.0.1",
"@wordpress/babel-plugin-import-jsx-pragma": "1.1.3",
"@wordpress/babel-preset-default": "3.0.2",
"@wordpress/env": "^4.8.0",
"@wordpress/stylelint-config": "19.1.0",
"allure-commandline": "^2.17.2",
"allure-playwright": "^2.0.0-beta.16",

14
plugins/woocommerce/tests/e2e/README.md
View File

@ -122,7 +122,7 @@ Run the following in a terminal/command line window
- `pnpm install`
- `pnpm exec turbo run build --filter=woocommerce`
- `pnpm -- turbo run build --filter=woocommerce`
- `npm install jest --global` (this only needs to be done once)
@ -161,7 +161,7 @@ Note that running `pnpm docker:down --filter=woocommerce` and then `pnpm docker:
To run e2e tests in headless mode use the following command:
```bash
pnpm exec turbo run e2e --filter=woocommerce
pnpm -- turbo run e2e --filter=woocommerce
```
### How to run tests in non-headless mode
@ -169,7 +169,7 @@ pnpm exec turbo run e2e --filter=woocommerce
Tests run in headless mode by default. However, sometimes it's useful to observe the browser while running or developing tests. To do so, you can run tests in a non-headless (dev) mode:
```bash
pnpm exec turbo run e2e:dev --filter=woocommerce
pnpm -- turbo run e2e:dev --filter=woocommerce
```
The dev mode also enables SlowMo mode. SlowMo slows down Puppeteer’s operations. This makes it easier to see what is happening in the browser.
@ -177,7 +177,7 @@ The dev mode also enables SlowMo mode. SlowMo slows down Puppeteer’s operation
By default, SlowMo mode adds a 50 millisecond delay between test steps. If you'd like to override the length of the delay and have the tests run faster or slower in the `-dev` mode, pass `PUPPETEER_SLOWMO` variable when running tests as shown below:
```
PUPPETEER_SLOWMO=10 pnpm exec turbo run e2e:dev --filter=woocommerce
PUPPETEER_SLOWMO=10 pnpm -- turbo run e2e:dev --filter=woocommerce
```
The faster you want the tests to run, the lower the value should be of `PUPPETEER_SLOWMO` should be.
@ -201,7 +201,7 @@ E2E_RETRY_TIMES=2 pnpm exec wc-e2e test:e2e
Tests run in headless mode by default. While writing tests it may be useful to have the debugger loaded while running a test in non-headless mode. To run tests in debug mode:
```bash
pnpm exec turbo run e2e:debug --filter=woocommerce
pnpm -- turbo run e2e:debug --filter=woocommerce
```
When all tests have been completed the debugger remains active. Control doesn't return to the command line until the debugger is closed. Otherwise, debug mode functions the same as non-headless mode.
@ -212,7 +212,7 @@ To run an individual test, use the direct path to the spec. For example:
```bash
cd plugins/woocommerce
pnpm exec wc-e2e test:e2e ./tests/e2e/specs/wp-admin/create-order.test.js
pnpm -- wc-e2e test:e2e ./tests/e2e/specs/wp-admin/create-order.test.js
```
### How to skip tests
@ -380,6 +380,6 @@ The [WooCommerce E2E Tests Boilerplate repo](https://github.com/woocommerce/wooc
## Debugging tests
The test sequencer (`pnpm exec turbo run e2e --filter=woocommerce`) includes support for saving [screenshots on test errors](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/e2e-environment#test-screenshots) which can be sent to a Slack channel via a [Slackbot](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/e2e-environment#slackbot-setup).
The test sequencer (`pnpm -- turbo run e2e --filter=woocommerce`) includes support for saving [screenshots on test errors](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/e2e-environment#test-screenshots) which can be sent to a Slack channel via a [Slackbot](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/e2e-environment#slackbot-setup).
For Puppeteer debugging, follow [Google's documentation](https://developers.google.com/web/tools/puppeteer/debugging).

438
pnpm-lock.yaml
View File

File diff suppressed because it is too large Load Diff