WordPress Contributor Toolkit (Electron)
Make WordPress posts:
The WordPress Contributor Toolkit is a desktop Electron application (macOS on Apple Silicon, Windows, and Linux) that takes a contributor from nothing to a working development environment for WordPress Core or Gutenberg, lets them try the work that already exists on a Trac ticket or a GitHub issue, and lets them send their own change back: as a pull request, a Trac attachment, or a patch for a mentor. No Git, Node.js, npm or Docker on the host, and no push credential written to disk.
Why
One of the most common complaints from Contributor Day facilitators is this: participants spend the entire session trying to set up their local environment and never get to actually contribute.
Before writing a single line of code, a first-time WordPress core contributor typically needs to install Git, Node.js, npm, Docker, configure everything correctly, and troubleshoot whatever breaks along the way. At in-person events, this alone can take hours — sometimes the full day.
Setup is the first wall, not the only one. A newcomer with a running environment still has to find whether somebody already wrote a patch for the ticket, get that patch into their checkout, understand why it does not apply when it does not, and work out how to send a change back to a project that reviews on Trac but takes pull requests on GitHub. Each of those steps has its own tooling and its own way to fail quietly.
The toolkit aims to remove that whole path, not just its first step.
What you can do with it
Each of these has a page in the user guide.
- Create a WordPress Core or Gutenberg development site with nothing installed on the host. A Core site is a
wordpress-develop checkout; a Gutenberg site is a gutenberg checkout served as a plugin in a stock WordPress. The clone, the dependency install and the first build run as one continuous chain rather than four clicks.
- Link a Trac ticket to a Core site and read its facts in the app: summary, status and resolution, type, milestone, component, keywords, age. A ticket can also arrive from a browser: the app answers
wpct://ticket/62281 links and offers the ticket to the site you have open. On a Gutenberg site, link a GitHub issue instead, and the app lists the pull requests that cite it.
- Try the work that already exists on it: pull requests are checked out on their own branches with the author's commits, on both projects, while on Core
.diff and .patch files are previewed and applied to the current ticket as removable layers. When a patch file will not apply, the app says which regions failed and why, and leaves the checkout untouched.
- Hold work for several tickets or issues in one site. Each one gets its own branch inside the site, so moving between them is a file swap of seconds instead of another clone and another install.
- Run the site and debug it: a debug log tab with fatals surfaced instead of hidden behind the recovery screen, the database, , and using the Node.js runtime the app bundles.
Documentation
The user guide lives at https://wordpress.github.io/contributor-toolkit/ — installing the app, creating a site, working on a Trac ticket, applying patches and PRs, and submitting your changes as a pull request, a Trac attachment, or a patch for a mentor. What follows here is only what a contributor to this repository needs.
Getting started
Just using the app
Download the latest packaged build from the Releases page and follow Getting started in the user guide — it covers picking the right file per platform, the macOS Gatekeeper notes, and the first-contribution walkthrough.
Build from source
Requirements: a recent Node.js to build the Electron app itself (runtime for the app is bundled).
npm install
npm start # run Electron + renderer in watch mode
# Package installers (no publishing):
npm run dist # all configured targets
npm run dist:win # Windows (x64 by default)
npm run dist:win:arm64
The renderer is bundled by esbuild into src/renderer/index.js and index.css. Those are generated files, are not committed, and are rebuilt by npm install, npm start and every npm run dist — so there is no bundling step to remember after changing src/renderer/index.jsx or the components and hooks it imports from src/renderer/components/ and src/renderer/hooks/. npm run build:once still exists if you want to rebuild on its own.
Output goes to dist/. On Linux, npm run dist creates an AppImage. macOS packages use the build machine's architecture, and the published macOS builds currently target Apple Silicon (arm64) only.
App icon
This app uses the official WordPress “W mark” as its icon.
- Source SVG:
build/wordpress-wmark.svg
- Packaged icons:
build/icon.icns (macOS), build/icon.png (Linux), build/icon.ico (Windows)
Electron Builder picks these up via build configuration in package.json.
Technical notes
How the app works from a user's point of view — the toolchain it bundles, keeping a site up to date with trunk, what SQLite does and doesn't cover — is documented in the user guide, not here.
Why Electron?
- WordPress core relies on Node.js, npm, and webpack for its build system. Electron is an easy way to install Node.js on all major platforms.
- It's a single, self-contained file. It's easy to distribute and install – it can be distributed on a USB sticks if everything else fails.
Ideas and future work
- Integrate Playground's XDebug.
- Explore bundling MySQL server with the app.
- Potentially integrate with Studio to benefit from wp-cli integration and other Studio features.
- Resolve conflicts in the app. Branches, commits and pushes are already handled for each work item, but when a work item's branch cannot move onto current trunk, the app still hands it to a mentor.
- Internationalization: the app's interface available in several languages, not only English.
Download stats
Release downloads are the only usage signal this project has, and GitHub keeps no history of them, so a weekly workflow records the counts to a metrics branch. See STATS.md for how to read them and what they do and don't measure.
Contributing
Much of the work here happens with the support of AI coding agents, and the quality bar is held by a set of guardrails rather than by trusting the agent. See CONTRIBUTING.md for what runs on every pull request (repo-wide lint, unit tests and end-to-end journeys on macOS and Windows) and the single review standard to run yourself before opening one, as the /self-review skill in Claude Code, or by following the standard directly on any other agent.
License
GPLv2 or later. See LICENSE.
