Blog

How to Contribute to WordPress | Part 1

October 26, 2026

On this page

Revised and updated in October 2026 against the official documentation (the Core Handbook, Test Handbook, and wordpress-develop and Gutenberg repositories). Intended for people making their first code or testing contribution.

1. Why contribute to Core

WordPress is free software, maintained by people and companies who give their time to the project. Five for the Future, proposed by Matt Mullenweg in 2014, recommends that organizations whose businesses depend on the ecosystem dedicate around 5% of their resources to WordPress. There is now an official page (wordpress.org/five-for-the-future) where companies and individuals register their commitment.

For theme and plugin developers, contributing brings practical benefits: you understand the APIs your work depends on, learn about changes coming in each release earlier, and detect incompatibilities before they reach production. Every accepted contribution also receives recognition through props in the commit message and release credits.

It is not all code. You can contribute by testing patches, writing automated tests, reviewing accessibility, or improving documentation. This guide focuses mainly on code and testing, two common ways to get started with Core and Gutenberg.

2. Checklist: what you need before starting

Accounts and communication

A WordPress.org account (used for Trac, Slack, and the Make blogs).
Access to the official Slack (make.wordpress.org/chat), and membership in #core, #core-test, and #core-editor. For accessibility questions, join #accessibility.
A GitHub account linked to your WordPress.org profile (Profile → Account & Security → Connections). Without this connection, your pull requests will not automatically earn you props.

Tools on your computer

Git installed (and optionally GitHub CLI). You only need SVN if you prefer working with the official Subversion repository.
Node.js 24 and npm 11 (the versions currently required by wordpress-develop). nvm is recommended for switching versions with nvm use.
Docker Desktop (or a compatible alternative such as OrbStack, Colima, or Rancher Desktop), installed and running.
Composer, required for PHPCS and Gutenberg’s PHP tests.
An editor with support for ESLint and PHP_CodeSniffer.

Repositories

A fork and clone of github.com/WordPress/wordpress-develop (Core).
A fork and clone of github.com/WordPress/gutenberg (the block editor).
A local environment started and working at least once (see section 3).

Essential reading

Core Contributor Handbook: make.wordpress.org/core/handbook.
WordPress Coding Standards (PHP, JavaScript, CSS, HTML, and accessibility): developer.wordpress.org/coding-standards.
The Trac guide: “How We Use Our Bug Tracker” in the Core Handbook.
WordPress AI Guidelines, if you plan to use AI tools: make.wordpress.org/ai/handbook/ai-guidelines/.
For Gutenberg: docs/contributors/code/getting-started-with-code-contribution.md and testing-overview.md in the repository.
Test Handbook: make.wordpress.org/test/handbook.

3. Set up a local Core environment

The development repository (wordpress-develop) is different from the WordPress package you download for a website. It includes automated tests, build-tool configuration, and source code in src/. JavaScript and CSS are generated through a build process (Grunt, run through npm).

Recommended option: Git and the included Docker environment

git clone https://github.com/<your-username>/wordpress-develop.git
cd wordpress-develop
npm install
npm run build:dev
npm run env:start
npm run env:install

The site becomes available at http://localhost:8889 (username admin, password password). While working, run npm run dev to watch for changes and rebuild automatically. Other useful commands:

npm run env:cli — <command>: runs WP-CLI inside the container.
npm run env:stop, npm run env:restart: stop and restart the environment.
npm run env:reset: resets the environment and deletes the database.

With this environment, wp-tests-config.php and the test database are created automatically. By default, the server serves the src/ directory (LOCAL_DIR=src in .env), which works correctly after npm run build:dev. To test the final built version, run npm run build and change LOCAL_DIR to build.

If you use an Apple Silicon Mac with an older version of MySQL (5.7 or earlier) or MariaDB 5.5, the README instructs you to create a docker-compose.override.yml that sets the database platform to linux/amd64.

Alternative option: SVN and your own server

SVN remains the official version control system (committers submit changes there), and you can work with it:

svn co https://develop.svn.wordpress.org/trunk/ wordpress-develop
cd wordpress-develop
npm install
npm run build:dev

If you use your own server (MAMP, Local, or LAMP), copy wp-config-sample.php to wp-config.php in the repository root and configure your database. For tests, copy wp-tests-config-sample.php to wp-tests-config.php and point it at a different database.

Warning: the PHPUnit suite drops and recreates tables (DROP TABLE / CREATE TABLE). If wp-tests-config.php points to your development site’s database, you will lose all its data.

PHP version

Since WordPress 7.0 (released in May 2026), the minimum supported PHP version is 7.4; the recommended version is 8.3 or later. If your change involves PHP, avoid syntax unavailable in PHP 7.4 (such as match, named arguments, or union types, which arrived in PHP 8.0). The Docker environment lets you change versions through LOCAL_PHP in the .env file.

Tool / file	Command or location	Purpose
Git / SVN	git clone from your fork or svn co https://develop.svn.wordpress.org/trunk/	Get and synchronize trunk’s code.
Node.js / npm	npm install	JavaScript dependencies and build tools.
Grunt (through npm)	npm run build:dev, npm run build, npm run dev	Build, minify, and watch for changes. There is no need to install grunt-cli globally; you can use npm run grunt — <task>.
Docker	npm run env:start	An isolated web server, PHP runtime, and database.
wp-config.php	Repository root	Local site configuration (automatic with Docker).
wp-tests-config.php	Repository root	An isolated database for PHPUnit (automatic with Docker).

4. Find tickets in Trac

Core work is organized in Trac (core.trac.wordpress.org). Each bug or enhancement is a ticket with a number, components, and keywords indicating its status. Before changing code, read “How We Use Our Bug Tracker” in the Core Handbook.

Useful reports to start with:

Good First Bugs (good-first-bug): narrowly scoped tickets reviewed by the Core team as suitable for beginners. The “Unclaimed” view shows tickets nobody has taken. A common task is updating (“refreshing”) old patches that no longer apply to trunk.
Needs Patch (needs-patch): the problem is confirmed, but there is no proposed code change yet. Tickets targeted for the next release often receive review sooner.
Needs Unit Tests (needs-unit-tests): tests are needed to reproduce the bug or validate the patch. This is a good way to learn how the code works internally.
Needs Testing (needs-testing): a patch exists and someone needs to test it and report the result. Ideal for a first contribution.
Next Major / Next Minor Release: tickets in the next release cycle, filterable by workflow (PHP, JavaScript, documentation, or UI).
Reports dashboard (/reports/ and /tickets/): includes personal views such as your pending patches and comments.

If you are unsure whether a ticket is still relevant or which approach is best, comment on the ticket or ask in #core on Slack. Asking questions is normal and saves work in the wrong direction.

Gutenberg changes do not go through Trac: they are managed as issues and pull requests on GitHub (github.com/WordPress/gutenberg). Good First Issue and Needs Testing labels serve the same purpose as their Trac equivalents.

5. Workflow: from a ticket to a patch or pull request

Before starting a new ticket

Start from a clean, up-to-date trunk so your change does not include leftovers from other tickets.

With Git:

git status
git checkout trunk
git pull upstream trunk
git checkout -b 12345-short-description
npm run build:dev

With SVN:

svn diff            # inspect local changes
svn revert -R .     # discard all local changes
svn up              # update from the server
npm run build:dev

Option A: a GitHub pull request (the most common approach today)

Make your changes in a branch of your wordpress-develop fork and push it.
Open a pull request against WordPress/wordpress-develop. Include the full Trac ticket URL in the description (for example, Trac ticket: https://core.trac.wordpress.org/ticket/12345) and enable the option that allows maintainers to edit your branch.
The PR will appear automatically on the Trac ticket. General PR comments are synchronized with Trac but do not notify ticket subscribers, so leave a comment on Trac as well.

PRs are not merged on GitHub: a committer applies the change in SVN. A PR without an associated Trac ticket will not be considered.

Option B: a patch file in Trac

To apply a patch someone else has uploaded to a ticket:

npm run grunt -- patch:12345

The patch task (from the grunt-patch-wordpress package, created by Aaron Jorbin) queries Trac, lists the ticket’s patches, and applies the one you choose. It also accepts a patch URL or a GitHub pull request URL. The manual alternative is to download the file and run patch -p0 < 12345.diff from the repository root; -p0 is necessary because WordPress patches retain paths from the repository root (src/, tests/).

To create your patch:

svn diff > 12345.diff
# or, with Git:
git diff trunk --no-prefix > 12345.diff

Name the file after the ticket number (12345.diff or 12345.patch). If that name already exists, Trac renames it (12345.2.diff). Do not include generated files such as minified JavaScript or RTL CSS. Upload it using Attach file on the ticket.

Update the ticket

After uploading the patch or opening the PR, edit the ticket’s keywords: remove needs-patch or needs-refresh and add has-patch (and needs-testing if someone needs to test it). Committers normally close or resolve tickets, so do not use resolution options unless instructed to do so.

6. AI agents and skills in the Gutenberg repository

Gutenberg includes files intended for AI coding assistants. They use “progressive discovery”: the agent loads only the context needed for a task instead of reading everything at once.

AGENTS.md in the root: general project rules and basic commands (installation, build, lint, and tests).
AGENTS.md by directory: for example, packages/components/AGENTS.md is read only when working in that folder.
Skills in .agents/skills/<name>/SKILL.md: procedures for specific tasks. Current examples include testing, defensive-data-design, package-runtime-compatibility, and several design-system skills.
References within each skill (references/): longer documents the agent reads only when a step requires them. For example, the testing skill links to references/jest.md, php.md, and e2e.md.
CLAUDE.md: contains only the line @AGENTS.md so Claude Code uses the same file.

The project’s principle is that rules belong in public documentation (for example, docs/contributors/code/), and agent files only point to it. If a rule is useful to an agent, it is also useful to a person; duplicating it makes the copies drift apart.

Each SKILL.md starts with a YAML header containing name and description, with the description stating when to use it:

---
name: testing
description: Use when writing, running, or debugging tests in the Gutenberg repository.
---

Among other requirements, Gutenberg’s testing skill says not to make a test pass by weakening it (looser assertions, added waits, or skipped cases without disclosure). If you create or modify a skill, run:

npm run agents:setup # regenerate the skill catalog for supported agents
npm run lint:md:docs # validate documentation Markdown formatting

The rules for using AI in contributions and disclosing that use are in section 7.

7. Recommendations for using AI in contributions

WordPress allows AI tools (GitHub Copilot, Claude Code, Codex, ChatGPT, and similar tools) to assist with contributions. Since January 2026, the AI team’s official AI Guidelines have been available (make.wordpress.org/ai/handbook/ai-guidelines/), and the wordpress-develop and Gutenberg pull request templates include a required “Use of AI Tools” section. The guidelines are an initial version (v0) and may change, so review them before each substantial contribution.

The five principles

You are responsible. AI can help, but it is not a contributor. Everything you submit is your responsibility, whether you wrote it or a tool generated it. Review AI output as you would code from someone you do not know.
Transparency. Disclose significant AI use in the PR description or a Trac ticket comment. Disclosure is not viewed negatively; it helps reviewers.
Compatible licensing. WordPress is GPLv2 or later. Do not use tools whose terms prevent you from using their output under the GPL, do not use AI to “rewrite” incompatibly licensed code, and never remove existing license headers or attributions.
This also applies beyond code. Images, screenshots, documentation, and Learn materials must be GPL-compatible. CC0 is acceptable for media; avoid licenses requiring attribution or share-alike terms, or imposing noncommercial or no-derivatives restrictions.
Quality before quantity. The guidelines explicitly reject “AI slop”: generic descriptions, large blocks of unreviewed code, invented APIs, hooks, functions, or tickets, and overengineered code. Maintainers may close contributions that show little human involvement.

How to disclose AI use

Complete the “Use of AI Tools” section in the PR template. If you contribute a patch through Trac, include it in your comment. The Core template’s example format is:

AI assistance: Yes
Tool(s): Claude Code
Model(s): <model used>
Used for: Initial code skeleton and test suggestions; final implementation
and tests were reviewed and edited by me.

There is no need to disclose trivial assistance, such as suggesting a variable name or rearranging imports. If significant undisclosed use is discovered, the merge or commit may be delayed or blocked.

Recommended uses

Understand unfamiliar code: ask for an explanation of a function, hook, or component flow before changing it.
Suggest a code skeleton, refactor, or alternative approach that you then evaluate yourself.
Generate boilerplate you can validate: test structure, data providers, and fixtures.
Suggest edge cases for testing and turn manual steps into automated tests.
Draft comments, inline documentation, dev notes, or PR descriptions that you then revise.
Translate text, always with review by someone fluent in the language.
Use Gutenberg’s AGENTS.md files and skills (section 6), which already provide the project commands and rules.

What to avoid

Submitting changes you do not fully understand.
Dependencies, patterns, or APIs that do not follow WordPress standards.
Asking for “the same code as library X” or accepting output that resembles a known project with an incompatible license.
Tests that depend on imaginary APIs or unstable external services.
Links, citations, or ticket numbers you have not checked.
Bug reports generated without reproducing the problem in a real installation.
Using AI as the only reviewer: human review is required.

Checklist before submitting an AI-assisted contribution

I read every line and removed anything I cannot explain.
The code meets WordPress coding, security, and performance standards, including the minimum PHP version (7.4).
I checked that the functions, hooks, and options used actually exist.
I added or updated tests and reviewed the names and cases suggested by AI.
I ran the relevant suites and included the commands in the PR description.
The PR is small, with clear commits, and the description reflects what I actually did and tested.
I completed the “Use of AI Tools” section.
I can explain during review what AI generated and what I wrote myself.

Practical tips for coding agents

Give the agent specific context: the ticket number, affected file, and expected behavior. Ask it to read the code and propose a plan before editing.
Ask it to write a failing test that reproduces the bug first, so you can check that it understood the problem.
In Gutenberg, keep agent-run E2E tests headless: interactive options such as –ui or –headed can leave the session blocked waiting for input.
Do not let it publish on your behalf: Trac comments, PRs, and review responses should come from you, in your own words and with your own judgment.
If you are unsure whether a tool or its output is GPL-compatible, ask in #core-ai or #core on Slack before submitting.

8. Contribute testing to Core and Gutenberg

There are two ways to contribute testing, and both are highly valued: manually testing other people’s patches and PRs, and writing automated tests.

Manually test patches and PRs

This is the quickest way to make a useful first contribution, and you do not need to write code.

Look for tickets marked needs-testing in Trac, or PRs labeled Needs Testing in Gutenberg.
Read the ticket or PR and its test instructions. Reproduce the bug without the patch first, to confirm it exists.
Apply the change using one of the options below.
Check that the patch fixes the problem, does not break nearby behavior, and works across browsers, themes, or keyboard and screen-reader use where relevant.
Publish a report on the ticket or PR. The Test Handbook provides a “Patch Testing” template and the Test Reports plugin, which fills in environment details. A report includes the patch or PR tested; the environment (operating system, browser, PHP and WordPress versions, theme, and plugins); steps followed; expected and observed results; and screenshots or video where useful.

Ways to apply the change you want to test:

WordPress Playground: if the ticket has a PR, the bot leaves a Playground link on the PR that creates a disposable site with the change applied. You can also use playground.wordpress.net and its options for testing Core or Gutenberg PRs. No installation is required.
Local Core environment: npm run grunt — patch:12345 or the PR URL.
Local Gutenberg environment: gh pr checkout <number>, then npm install and npm run build.

If the patch works, say so clearly. If it fails or no longer applies to trunk, explain what happened and suggest needs-refresh in Trac. Testing questions belong in #core-test.

9. Closing thoughts

WordPress powers more than 40% of websites, and every change to Core or Gutenberg reaches millions of installations. That is why careful work matters: a well-tested patch, a test that prevents a regression, or a component usable with a keyboard. A useful starting sequence is to prepare the environment, test a needs-testing patch, write a test for a needs-unit-tests ticket, and then take a good-first-bug. If you get stuck, ask in Slack.

Sources

Gutenberg: AGENTS.md, .agents/skills/, and docs/contributors/code/testing-overview.md in github.com/WordPress/gutenberg

Core Contributor Handbook: make.wordpress.org/core/handbook

wordpress-develop README: github.com/WordPress/wordpress-develop

Working with Patches: make.wordpress.org/core/handbook/tutorials/working-with-patches/

GitHub Pull Requests for Code Review: make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/

Dropping support for PHP 7.2 and 7.3 (January 2026): make.wordpress.org/core/2026/01/09/dropping-support-for-php-7-2-and-7-3/

AI Guidelines (WordPress AI team, January 2026): make.wordpress.org/ai/handbook/ai-guidelines/

wordpress-develop pull request template: github.com/WordPress/wordpress-develop/blob/trunk/.github/pull_request_template.md

Accessibility Coding Standards: developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/

WebAIM Screen Reader User Survey #10: webaim.org/projects/screenreadersurvey10/

Test Handbook (Patch Testing, Test Core Tickets with Playground, Test Gutenberg with Playground): make.wordpress.org/test/handbook