We’re excited to announce a significant update to how WPGraphQL is developed and released. The WPGraphQL repository has been restructured as a **monorepo**, and we’ve modernized our release process using **release-please**. Here’s what you need to know.

TL;DR

– For (most) users: Nothing changes! Install WPGraphQL the same way you always have.

– For contributors: PRs now target main (not develop).

– For the ecosystem: This paves the way for official extensions to join the monorepo, which should allow faster shipping and iteration

What Changed?

Monorepo Structure

The WPGraphQL plugin code has moved from the repository root into a `plugins/` directory:

wp-graphql/

├── plugins/

│ └── wp-graphql/ # The WPGraphQL plugin lives here now

├── docs/ # Contributor documentation

├── .wp-env.json # Shared development environment

├── package.json # Root workspace configuration

└── turbo.json # Build orchestration

Why? This structure allows us to host multiple official WPGraphQL plugins in a single repository, sharing CI/CD infrastructure, testing tools, and development workflows.

Simplified Git Workflow

We’ve moved from a develop / master branching model to a single main branch:

BEFORE	AFTER
Branch from `master`	Branch from `main`
PR Targets `develop`	PR Targets `main`
Releases triggered when `developed` merged to master	Releases created when `release-please` PR is merged to `main`

Automated Releases with release-please

We’ve replaced our custom changeset system with release-please, Google’s release automation tool. This means, much of the same automated release tooling we had will continue to function, but should be more stable using release-please instead of our bespoke scripts and workflows:

Automatic version bumps based on PR titles
Auto-generated changelogs from merged PRs
Release PRs accumulate changes until we’re ready to ship

New GitHub Release Format

If you follow WPGraphQL releases on GitHub, you’ll notice the changelog format will look a bit different.

Before (custom scripts):

## Changelog

**Bump Type:** minor

### ✨ New Features

* feat: add new field (#1234)

### 🐛 Bug Fixes

* fix: resolve issue (#1235)

### 👏 Contributors

Thanks to @contributor1, @contributor2

After (release-please):

## What's Changed

### Features

* add new field (#1234)

### Bug Fixes

* resolve issue (#1235)

The content is largely the same, it’s generated from the same PR titles, but the formatting is release-please’s default style. We may customize this over time, but the core information (what changed, which PRs, version bump) remains the same.

New Tag Format for Multiple Plugins

With multiple plugins in the monorepo, release tags will now include the plugin name:

Before (single plugin)	After (monorepo)
v2.7.0	wp-graphql/v2.7.0
–	wp-graphql-smart-cache/v1.5.0

Each plugin gets its own:

GitHub Release with its own changelog
Git tag prefixed with the plugin name
Zip artifact attached to the release

⚠️ Git Updater No Longer Supported

If you use Git Updater to update WPGraphQL directly from GitHub releases, you will need to migrate to a different installation method.

After consulting with the Git Updater maintainer, we’ve confirmed that Git Updater doesn’t work well with monorepo structures. With multiple plugins in a single repository, each with their own prefixed tags (e.g., wp-graphql/v2.7.0, wp-graphql-smart-cache/v1.5.0), as Git Updater currently cannot reliably determine which release corresponds to which plugin.

We have removed the Git Updater headers (GitHub Plugin URI and Release Asset) from the WPGraphQL plugin, and will do the same for any WPGraphQL plugins that are migrated into the new monorepo structure.

Recommended alternatives:

WordPress.org: Install from the WordPress.org plugin directory
Composer: composer require wpackagist-plugin/wp-graphql (via WordPress Packagist)
Manual download: Download the zip from GitHub Releases and upload to your site (requires manually doing this for each update)

We apologize for any inconvenience this causes Git Updater users. We believe that the benefits of the monorepo structure, such as shared CI/CD, coordinated testing, and streamlined releases across the WPGraphQL ecosystem, outweigh maintaining a specialized update mechanism that only a small subset of users relied upon.

What This Means for Users

For most users, nothing changes! 🎉

You can still install WPGraphQL:

From WordPress.org
Via Composer: composer require wp-graphql/wp-graphql
By downloading from GitHub Releases

The plugin works exactly the same way it always has.

⚠️ If You Use Local Symlinks

If you’re a contributor or power user who symlinks the WPGraphQL repo directly into a local WordPress installation, you’ll need to update your symlinks:

# Before

- /path/to/wp-graphql

# After

+ /path/to/wp-graphql/plugins/wp-graphql

For example, if your WordPress plugins directory previously linked to:

~/Developer/wp-graphql

It should now link to:

~/Developer/wp-graphql/plugins/wp-graphql

This would only affect developers that clone the repo and symlink it.

What This Means for Contributors

PR Titles (Still Matter!)

This isn’t completely new. Our previous system also used PR titles to generate changelogs and determine version bumps. That continues with our migration to release-please.

PR Title Prefix	What It Does	Version Bump
`feat:`	New Feature	Minor (1.x.0)
`fix:`	Bug fix	Patch (1.0.x)
`feat!:` or `fix!:` or `perf!:`	Breaking change	Major (x.0.0)
`docs:`, `chore:`, `ci:`, `test:`	Maintenance	No release

What’s different: The ! breaking change marker is now restricted to release-triggering prefixes (feat!:, fix!:, perf!:). Previously, something like ci!: might have been interpreted as a breaking change, but now it will be blocked by CI validation since ci: commits don’t trigger releases anyway.

Your individual commits within the PR don’t need to follow this format (although it might be helpful if they do) only the PR title matter for the release-please changelog generation and version bumping.

Version Placeholders in Code

When adding new features, we use version placeholders in docblocks that get automatically replaced during the release process. We’ve switched from custom placeholders to release-please’s native format:

Before	After
`@since next-version`	`@since x-release-please-version`
`@next-version`	`x-release-please-version`

For example, when adding a new function:

/**
 * My new function.
 *
 * @since x-release-please-version
 */
function my_new_function() { ... }

Release-please will automatically replace x-release-please-version with the actual version number (e.g., 2.7.0) when creating the release.

Updated File Paths

If you have an open PR, you’ll need to update your file paths:

- src/Type/ObjectType/Post.php

+ plugins/wp-graphql/src/Type/ObjectType/Post.php

PRs Target `main`

We no longer use a develop branch. All PRs should target main directly.

Why We Made These Changes

More Time for What Matters

As a project with primarily one core maintainer, every hour spent debugging CI tooling or reinventing release automation is an hour not spent on bug fixes, new features, or helping the community.

Our previous release system used custom scripts totaling 1,000+ lines of JavaScript. The release-please action replaces most of that with a ~150-line workflow configuration. This isn’t just about fewer lines of code, it’s about adopting battle-tested tooling maintained by Google instead of maintaining bespoke scripts ourselves.

The bottom line: Less time on CI plumbing means more time for WPGraphQL’s core functionality and ecosystem.

Scalability for the Ecosystem

The monorepo structure allows us to bring official WPGraphQL extensions into the same repository:

WPGraphQL Smart Cache
WPGraphQL IDE
WPGraphQL for ACF
And more. . .including experimental plugins like WPGraphQL Subscriptions

Each plugin will have independent versioning and separate releases, but they’ll share:

CI/CD infrastructure
Testing environments
Development tooling
Release automation

Simpler Contributor Experience

Wit the transition to release-please we’re transitioning to a single-branch workflow. Contributors will now branch off of main and open Pull Requests back to main.

What’s Coming Next?

Phase 2: Migrate Extension Plugins, starting with WPGraphQL Smart Cache

We’re preparing to import extension plugins into the monorepo, and we will start with WPGraphQL Smart Cache

This will:

Validate our multi-plugin release workflow
Establish patterns for future extensions
Make it easier to test Smart Cache alongside core WPGraphQL
Make it easier to migrate functionality from Smart Cache into core WPGraphQL if/when we decide to pursue this path

Future Extensions

Once Smart Cache is integrated, we plan to bring in additional official plugins, such as WPGraphQL IDE, WPGraphQL for ACF and more, creating a more unified and streamlined development experience for the WPGraphQL ecosystem.

Getting Started with the New Structure

For Local Development

# Clone the repository

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

cd wp-graphql

# Install dependencies

npm install

# Start the development environment

npm run wp-env start

The WordPress site will be available at http://localhost:8888.

For Contributing

Fork the repository
Create a feature branch from main
Make your changes
Open a PR, targeting main, with a conventional commit-style title
Wait for CI checks to pass
A maintainer will review and merge

See our Contributing Guide for detailed instructions.

Questions?

💬 Join us on Discord
🐛 Open an issue on GitHub

We’re excited about this new chapter for WPGraphQL and can’t wait to see what we build together!

NOTE: This change was tracked in [GitHub Issue #3469](https://github.com/wp-graphql/wp-graphql/issues/3469)and implemented in [PR #3470](https://github.com/wp-graphql/wp-graphql/pull/3470).