Contributing

This document will be most useful for developers that want to contribute to WPGraphQL and want to run the docker container locally as well as utilize xdebug for debugging and tracing.

Note: WPGraphQL is now a monorepo. For detailed setup instructions, see the Development Setup Guide in the repository root.

Development Workflow

WPGraphQL uses several automated processes to maintain consistency and quality:

Conventional Commits
- PR titles must follow the format (e.g., feat:, fix:)
- Breaking changes use ! suffix (e.g., feat!:)
- See Conventional Commits for more details
Automated Releases
- release-please creates Release PRs automatically
- Changelog generated from PR titles
- Version bumps determined by commit types
Version Management
- Automatically updates version numbers via release-please
- Updates @since x-release-please-version placeholders to the actual version during the release process
- Maintains changelog in multiple formats (CHANGELOG.md, readme.txt)
Testing
- Script tests for automation code
- E2E tests for GraphiQL
- Version management validation
- Release simulation

In order to continue, you should follow steps to setup your local development environment.

Local Setup

Prerequisites

Ensure you have the following installed on your local machine:

Node.js 22+ and npm >= 10 (NVM recommended)
Docker
Git
PHP 7.4+ and Composer (if you prefer to run the Composer tools locally)

You can use Docker and the wp-env tool to set up a local development environment, instead of manually installing the specific testing versions of WordPress, PHP, and Composer. For more information, see the wp-env documentation.

Installation

WPGraphQL uses @wordpress/env to manage the local WordPress development and testing environment using Docker.

Clone the repository:

git clone [email protected]:wp-graphql/wp-graphql.git
cd wp-graphql

Install the NPM dependencies (from the repository root):

## If you're using nvm, make sure to use the correct Node.js version:
nvm install && nvm use

## Then install the NPM dependencies:
npm ci

Build the JavaScript assets (required for GraphiQL IDE and Extensions page):
```
npm run build
```
Note: The /build directory is gitignored. You must run this step for the GraphiQL IDE to function. If you skip this step, you’ll see a helpful message in the admin with instructions.
Start the wp-env environment to download and set up the Docker containers for WordPress:

(If you’re not using wp-env you can skip this step.)
```
npm run wp-env start
```
When finished, the WordPress development site will be available at http://localhost:8888 and the WP Admin Dashboard will be available at http://localhost:8888/wp-admin/. You can log in to the admin using the username admin and password password.

Composer dependencies are automatically installed when the environment starts via the afterStart lifecycle script.

(Optional) Manually install Composer dependencies if needed:

## To install Composer dependencies inside the Docker container:
npm run wp-env -- run tests-cli --env-cwd=wp-content/plugins/wp-graphql/ -- composer install

## Or: if you're running Composer locally:
composer -d plugins/wp-graphql install

Using XDebug

XDebug is installed via the wp-env environment, but is turned off by default. You can enable XDebug by passing the --xdebug flag when starting the wp-env environment.

# To turn it on:
npm run wp-env start -- --xdebug

# Or enable specific modes with a comma-separated list:
npm run wp-env start -- --profile,trace,debug

You can also connect your IDE to XDebug.

The following example is for Visual Studio Code (VSCode) using the PHP Debug extension

Create or add the following configuration to your .vscode/launch.json in the repository root. Restart VSCode. Start the debug listener before running the app or testing images.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "xdebugSettings": {
        "max_children": 128,
        "max_data": 1024,
        "max_depth": 3,
        "show_hidden": 1
      },
      "pathMappings": {
        "/var/www/html/wp-content/plugins/wp-graphql": "${workspaceFolder}/plugins/wp-graphql",
        // If you have WordPress core files in a directory for local development, you can add the location to the `pathMappings` for debug step through. For example:
        "/var/www/html": "/path/to/your/local/wordpress"
      }
    }
  ]
}

Releases

WPGraphQL uses release-please for automated versioning and releases. When contributing:

Your PR title must follow conventional commits format:
- feat: for new features (minor version bump)
- fix: for bug fixes (patch version bump)
- Add ! suffix for breaking changes: feat!: or fix!:
- Non-release types: docs:, chore:, ci:, test:, refactor: (no version bump)
Use the appropriate PR template:
- Go to Create New Pull Request
- The default template will show a “chooser” with links to specialized templates
- Click the appropriate template link for your contribution type:
  - 🐛 Bug Fixes - For fixing bugs with failing test → fix → passing test workflow
  - ✨ Features - For implementing new WPGraphQL features
  - 🧪 Experiments - For implementing or updating experiments
  - 📚 Documentation - For documentation improvements
  - 🔧 Refactoring - For code improvements without functional changes
  - 📦 Dependencies - For dependency updates and security fixes
  - 🛠️ Maintenance - For CI/CD, tooling, and configuration updates
- Fill out the template with your contribution details
Include in your PR description:
- Clear explanation of changes
- Breaking changes (if any)
- Upgrade instructions (if breaking)

Add @since x-release-please-version tags to new functions/classes docblocks:

/**
 * My new function.
 *
 * @since x-release-please-version
 * @param string $param Description.
 * @return string
 */
function my_new_function( $param ) { ... }

For deprecation functions, use x-release-please-version as the version parameter:

_deprecated_function( __FUNCTION__, 'x-release-please-version', 'new_function' );

These placeholders are automatically replaced with the actual version by release-please during the release process.

Release Process:
- PRs are merged to main via squash merge (PR title becomes commit message)
- release-please analyzes commits and creates/updates a Release PR
- The Release PR accumulates changes and shows the upcoming version bump
- When the Release PR is merged, a GitHub release is created and the plugin is deployed to WordPress.org

Development Workflow​

Local Setup​

Prerequisites​

Installation​