Code Contributions

This guide walks you through setting up your local development environment and contributing code to the Gutenberg project.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Node.js and npm

Gutenberg requires Node.js v20 and npm v10. We recommend using Node Version Manager (nvm) for easy installation and management.

# Using nvm
nvm install 20
nvm use 20

Git

Install Git for source control. You’ll also need a GitHub account to contribute.

Docker Desktop (Recommended)

Install Docker to use the wp-env package for local WordPress development.

On Windows 10 Home Edition, follow the Docker installation instructions for WSL2.

Alternatively, you can use Local, WampServer, or MAMP.

Composer (for PHP development)

Install Composer for PHP dependency management and testing.

Optional Tools

GitHub CLI: The GitHub CLI is helpful for checking out pull requests locally
Python: Required for some install scripts (may be pre-installed on your OS)

Setting Up Your Development Environment

1. Fork and Clone the Repository

Fork the Repository

Go to the Gutenberg repository on GitHub and click Fork to create a copy in your account.

Clone Your Fork

Clone your forked repository to your local machine:

git clone https://github.com/YOUR_GITHUB_USERNAME/gutenberg.git
cd gutenberg

Add Upstream Remote

Add the main Gutenberg repository as an upstream remote:

git remote add upstream https://github.com/WordPress/gutenberg.git
git remote -v

2. Install Dependencies and Build

# Install JavaScript and PHP dependencies
npm install
composer install

# Build Gutenberg in development mode with watch
npm run dev

# Or build for production
npm run build

Use npm run dev during development for continuous builds that automatically update as you change source files. The dev build includes additional warnings and errors to help with troubleshooting.

3. Set Up Local WordPress Environment

Using wp-env (Recommended)

The @wordpress/env package provides a quick way to create a WordPress environment using Docker:

# Check wp-env status
npm run wp-env status

# Start wp-env (only if not already running)
npm run wp-env start

# Stop wp-env
npm run wp-env stop

# Destroy the environment completely
npm run wp-env destroy

The wp-env start command creates a Docker container with WordPress and automatically activates your local Gutenberg build as a plugin.

Access Your Environment:

WordPress site: http://localhost:8888
Admin dashboard: http://localhost:8888/wp-admin/
- Username: admin
- Password: password
phpMyAdmin: http://localhost:9000

Using MAMP or Local

If you prefer MAMP or Local, create a symlink to the Gutenberg directory in your wp-content/plugins/ directory:

cd /path/to/wordpress/wp-content/plugins
ln -s /path/to/gutenberg gutenberg

Git Workflow

Gutenberg follows a standard pull request workflow:

Create a Feature Branch

Create a new branch for your changes using a descriptive name with a prefix:

git switch -c add/my-feature

Branch Naming Prefixes:

add/ - Add a new feature
update/ - Update an existing feature
fix/ - Fix an existing issue
try/ - Experimental feature
remove/ - Remove an existing feature

Make Your Changes

Make your code changes, following the coding guidelines. Test thoroughly.

Run Tests

Confirm all tests pass before committing:

# Run all JavaScript tests and linting
npm test

# Run all PHP tests and linting
npm run test:php

See the testing guide for more details.

Commit Your Changes

Commit with a good commit message:

git commit -m "Add gallery block feature"

Push to Your Fork

Push your branch to your forked repository:

git push -u origin add/my-feature

Create a Pull Request

Go to your forked repository on GitHub. GitHub will automatically detect your new branch and offer to create a pull request. Click the link and fill out the PR template.

Address Feedback

Respond to any code review feedback. Make additional changes locally and push them to the same branch. The PR will automatically update.

# Make changes, then:
git commit -m "Address review feedback"
git push

Share your work early by opening a pull request even before it’s complete. You can mark it as a draft to indicate it’s a work in progress.

Keeping Your Branch Up to Date

When working on long-running pull requests, you’ll need to keep your branch up to date with the main trunk branch:

# Fetch latest changes from upstream
git fetch upstream

# Rebase your branch on trunk
git checkout your-branch-name
git rebase upstream/trunk

# Force push (safely) to your fork
git push --force-with-lease origin your-branch-name

Always use --force-with-lease instead of --force when force pushing. This ensures you don’t accidentally overwrite someone else’s work.

Keeping Your Fork Synced

Regularly update your fork’s trunk branch:

git fetch upstream
git checkout trunk
git merge upstream/trunk
git push

Coding Standards

JavaScript

Follow WordPress JavaScript coding standards
Use ESLint for linting (automatically configured)
Use Prettier for formatting

Linting Commands:

# Check JavaScript linting
npm run lint:js

# Fix JavaScript linting issues automatically
npm run lint:js:fix

# Format code with Prettier
npm run format

PHP

Follow WordPress PHP coding standards
Use PHP_CodeSniffer for standards checking

PHP Linting Commands:

# Check PHP coding standards
npm run lint:php
# Or: vendor/bin/phpcs

# Fix PHP coding standards automatically
vendor/bin/phpcbf

# Fix specific file
vendor/bin/phpcbf path/to/file.php

Development Tools Setup

Visual Studio Code

We recommend configuring VS Code with the following extensions:

EditorConfig

Install EditorConfig for VS Code to automatically match the project’s editor rules.

ESLint

Install ESLint Extension and add to your settings:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

Prettier

Install Prettier - Code formatter and configure:

{
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

TypeScript

TypeScript support is built into VS Code. The project uses TypeScript via JSDoc to type check JavaScript files.

Pull Request Guidelines

Before Submitting

Ensure all tests pass
Fix all linting and formatting issues (enforced by CI)
Write tests for new functionality
Update documentation as needed

PR Best Practices

Non-trivial PRs should be preceded by a related issue
Keep PRs atomic—one conceptual change per PR
Write descriptive PR titles that explain what is being fixed, not how
Label your PR appropriately (e.g., [Type] Bug, [Type] Enhancement)

Example PR Titles:

✅ Good: “Fix editor breakage when clicking copy block button”
❌ Bad: “Check for nullable object in component”

Getting Your PR Reviewed

If you’re having trouble getting your PR reviewed:

Make sure it’s properly labeled
Ensure all CI checks pass
Ask for review in the #core-editor Slack channel
Tag relevant team members if appropriate

See How To Get Your Pull Request Reviewed for more tips.

Key Directories

Understanding the repository structure:

/packages/ - JavaScript packages (each has README.md and CHANGELOG.md)
/lib/ - PHP code
/lib/compat/wordpress-X.Y/ - Version-specific features
/phpunit/ - PHP tests
/docs/ - Documentation
- /docs/contributors/ - Contributing guides
- /docs/explanations/architecture/ - System architecture
- /docs/how-to-guides/ - Implementation tutorials
- /docs/reference-guides/ - API documentation

Common Pitfalls

PHP features in lib/compat/ MUST target a specific wordpress-X.Y/ subdirectory
block-editor is WordPress-agnostic—never add core-data dependencies to it
Avoid using private APIs in bundled packages
@wordpress/build is used by plugins targeting WordPress Core—avoid Gutenberg-specific changes

Get Involved

Prerequisites

Required Software

Optional Tools

Setting Up Your Development Environment

1. Fork and Clone the Repository

2. Install Dependencies and Build

3. Set Up Local WordPress Environment

Using wp-env (Recommended)

Using MAMP or Local

Git Workflow

Keeping Your Branch Up to Date

Keeping Your Fork Synced

Coding Standards

JavaScript

PHP

Development Tools Setup

Visual Studio Code

EditorConfig

ESLint

Prettier

TypeScript

Pull Request Guidelines

Before Submitting

PR Best Practices

Getting Your PR Reviewed

Key Directories

Common Pitfalls

Additional Resources

Next Steps

Testing Guide

Browse Issues

Build docs developers (and LLMs) love

Get Involved

​Prerequisites

​Required Software

​Optional Tools

​Setting Up Your Development Environment

​1. Fork and Clone the Repository

​2. Install Dependencies and Build

​3. Set Up Local WordPress Environment

​Using wp-env (Recommended)

​Using MAMP or Local

​Git Workflow

​Keeping Your Branch Up to Date

​Keeping Your Fork Synced

​Coding Standards

​JavaScript

​PHP

​Development Tools Setup

​Visual Studio Code

​EditorConfig

​ESLint

​Prettier

​TypeScript

​Pull Request Guidelines

​Before Submitting

​PR Best Practices

​Getting Your PR Reviewed

​Key Directories

​Common Pitfalls

​Additional Resources

​Next Steps

Testing Guide

Browse Issues

Build docs developers (and LLMs) love

Prerequisites

Required Software

Optional Tools

Setting Up Your Development Environment

1. Fork and Clone the Repository

2. Install Dependencies and Build

3. Set Up Local WordPress Environment

Using wp-env (Recommended)

Using MAMP or Local

Git Workflow

Keeping Your Branch Up to Date

Keeping Your Fork Synced

Coding Standards

JavaScript

PHP

Development Tools Setup

Visual Studio Code

EditorConfig

ESLint

Prettier

TypeScript

Pull Request Guidelines

Before Submitting

PR Best Practices

Getting Your PR Reviewed

Key Directories

Common Pitfalls

Additional Resources

Next Steps