woocommerce/DEVELOPMENT.md

92 lines
3.3 KiB
Markdown
Raw Permalink Normal View History

# Development
2021-10-06 05:02:52 +00:00
This document aims to provide as much context as possible to aid in the development of plugins, packages, and tools in the monorepo.
2021-10-06 05:02:52 +00:00
## Getting Started
2021-10-06 05:02:52 +00:00
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 prerequisites and setup described there.
2021-10-06 05:02:52 +00:00
### Plugin, Package, and Tool Filtering
2023-11-17 18:11:56 +00:00
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.
2021-10-06 05:02:52 +00:00
### Examples
2021-10-06 05:02:52 +00:00
2023-11-17 18:11:56 +00:00
Here are some examples of the ways you can use `pnpm` commands:
2021-10-06 05:02:52 +00:00
```bash
2023-11-17 18:11:56 +00:00
# Lint and build all plugins, packages, and tools.
2023-11-28 22:50:43 +00:00
pnpm lint && pnpm build
2021-10-06 05:02:52 +00:00
# Build WooCommerce Core and all of its dependencies
2023-11-17 18:11:56 +00:00
pnpm --filter='@woocommerce/plugin-woocommerce' build
2021-10-06 05:02:52 +00:00
2023-11-17 18:11:56 +00:00
# Lint the @woocommerce/components package
pnpm --filter='@woocommerce/components' lint
# Test all of the @woocommerce scoped packages
2023-11-17 18:11:56 +00:00
pnpm --filter='@woocommerce/*' test
# Build all of the JavaScript packages
2023-11-17 18:11:56 +00:00
pnpm --filter='./packages/js/*' build
# Build everything except WooCommerce Core
2023-11-17 18:11:56 +00:00
pnpm --filter='!@woocommerce/plugin-woocommerce' build
# Build everything that has changed since the last commit
2023-11-17 18:11:56 +00:00
pnpm --filter='[HEAD^1]' build
```
### Examples
2021-10-06 05:02:52 +00:00
Here are some examples of the commands you will make use of.
2021-10-06 05:02:52 +00:00
```bash
# Add a changelog entry for WooCommerce Core
2023-11-17 18:11:56 +00:00
pnpm --filter='@woocommerce/plugin-woocommerce' changelog add
2021-10-06 05:02:52 +00:00
# Create the woocommerce.zip file
2023-11-17 18:11:56 +00:00
pnpm --filter='@woocommerce/plugin-woocommerce' build:zip
2021-10-06 05:02:52 +00:00
```
## Plugin Development Environments
2021-10-06 05:02:52 +00:00
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.
2021-10-06 05:02:52 +00:00
```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
2021-10-06 05:02:52 +00:00
```
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.
2021-10-06 05:02:52 +00:00
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.
## Troubleshooting
### Installing PHP in Unix (e.g. Ubuntu)
Many unix systems such as Ubuntu will have PHP already installed. Sometimes without the extra packages you need to run WordPress and this will cause you to run into troubles.
Use your package manager to add the extra PHP packages you'll need.
e.g. in Ubuntu you can run:
```
sudo apt update
sudo apt install php-bcmath \
php-curl \
php-imagick \
php-intl \
php-json \
php-mbstring \
php-mysql \
php-xml \
php-zip
```