Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
154 lines (119 loc) · 5.01 KB

CONTRIBUTING.md

File metadata and controls

154 lines (119 loc) · 5.01 KB

Contributing to WooCommerce

This is a quick reference for common commands used during development. For broader contribution guidelines, see the Contributing to WooCommerce docs. For detailed development notes, see DEVELOPMENT.md.

Tooling

A POSIX-compliant OS (Linux, macOS) is assumed. On Windows, use WSL.

Initial install

# Use the pinned Node version from .nvmrc
nvm install
# Install JS and PHP dependencies
pnpm install

Monorepo filtering

This is a PNPM workspaces monorepo. Use --filter to target individual projects:

# Build WooCommerce Core + deps
pnpm --filter='@woocommerce/plugin-woocommerce' build
# Lint a specific package
pnpm --filter='@woocommerce/components' lint
# Build all JS packages
pnpm --filter='./packages/js/*' build
# Build only what changed
pnpm --filter='[HEAD^1]' build

See DEVELOPMENT.md for more filtering examples and tools/README.md for monorepo infrastructure details.

Local WordPress environment

The repository uses @wordpress/env (wp-env) for local development environments.

cd plugins/woocommerce
# Start the environment (creates it if needed, pulls latest config)
pnpm env:dev
# Stop the environment
pnpm env:stop
# Remove all environment files
pnpm env:destroy

Build

# Build everything
pnpm build
# Build WooCommerce Core
pnpm --filter='@woocommerce/plugin-woocommerce' build
# Create woocommerce.zip
pnpm --filter='@woocommerce/plugin-woocommerce' build:zip

For active development with file watching:

# Watch and rebuild on changes
pnpm --filter='@woocommerce/plugin-woocommerce' watch:build

Tests

# PHP unit tests (requires wp-env)
cd plugins/woocommerce
# Start the test environment
pnpm env:dev
# Run all PHP unit tests
pnpm test:unit:env
# Run a specific test class
pnpm test:unit:env -- --filter=TestClassName
# Watch mode
pnpm test:unit:env:watch

# E2E tests (requires Docker)
cd plugins/woocommerce
# Start the E2E environment
pnpm env:start
# Run Playwright E2E tests
pnpm test:e2e

# JavaScript tests
pnpm --filter='@woocommerce/admin-library' test:js
pnpm --filter='@woocommerce/block-library' test:js

See the unit tests README, E2E tests README, and performance tests README for full details.

Linting and static analysis

# Lint everything
pnpm lint
# Lint changed PHP files
pnpm --filter='@woocommerce/plugin-woocommerce' lint:php:changes
# Lint PHP changes on branch (vs trunk)
pnpm --filter='@woocommerce/plugin-woocommerce' lint:php:changes:branch
# Auto-fix PHP lint issues
pnpm --filter='@woocommerce/plugin-woocommerce' lint:php:fix -- path/to/file.php
# Lint JS/TS (ESLint)
pnpm --filter='@woocommerce/plugin-woocommerce' lint:lang:js

PHPStan:

cd plugins/woocommerce
composer exec -- phpstan analyse path/to/File.php --memory-limit=2G

See the Coding Standards docs and the WordPress Coding Standards for conventions.

Changelog

Every PR that changes code in a project requires a changelog entry:

# Interactive prompt for WooCommerce Core
pnpm --filter='@woocommerce/plugin-woocommerce' changelog add

Replace @woocommerce/plugin-woocommerce with the relevant package name if your changes affect a different project.

For the full PR workflow, changelog conventions, and coding guidelines, see Contributing to WooCommerce and the contribution docs.

Repository structure

plugins/                   # WordPress plugins
  woocommerce/             # WooCommerce Core plugin
    src/                   #   Modern PHP (PSR-4, DI container)
    includes/              #   Legacy PHP
    client/admin/          #   Admin React/TypeScript app
    tests/                 #   PHP unit, E2E, performance tests
packages/                  # Shared libraries
  js/                      #   JavaScript/TypeScript packages
  php/                     #   PHP packages
tools/                     # Monorepo utilities and scripts

See plugins/woocommerce/src/README.md for modern PHP architecture and tools/README.md for monorepo tooling.