Publishing a new release for WPGraphQL has historically required several manual steps—updating changelogs, determining semantic version bumps, preparing upgrade notices, and ensuring that every piece of documentation reflects the correct information. While I had a process in place, it wasn’t as efficient as it could be, and the potential for human error was always there.

Over the past few weeks, I set out to automate as much of this as possible. This blog post walks through why I tackled this, how I iterated on different approaches before landing on the final implementation, and where I see this evolving in the future.

Why Automate the Release Process?

When it comes to maintaining an open-source project like WPGraphQL, consistency and accuracy in releases are crucial. I had been following a structured but manual process that involved:

Writing and maintaining changelogs
Updating the readme.txt for WordPress.org
Ensuring proper semantic versioning (major, minor, patch)
Writing upgrade notices for breaking changes
Publishing the release

While this process worked, it was:

Time-consuming: Even with a checklist, it required multiple steps every time a release was prepared.
Prone to human error: Forgetting a step or misclassifying a change could lead to inconsistencies.
Hard to scale: As WPGraphQL continues to grow, I needed a more robust and repeatable approach.

By automating these steps, I aimed to:

✅ Save time by reducing the manual overhead of preparing releases
✅ Reduce errors by ensuring that every PR gets documented correctly
✅ Improve visibility into what’s changing in WPGraphQL releases
✅ Ensure consistency across releases and documentation

How I Got Here: Iterating on the Solution

My goal was to create a workflow that would automatically track changes from pull requests and use those to generate release notes, changelog entries, and semantic version bumps.

Exploring Solutions

I initially considered using @changesets/cli, a tool commonly used in JavaScript monorepos for managing changelogs and versioning. However, since WPGraphQL is a WordPress plugin (not a monorepo) and follows a different release structure, I opted to implement a custom approach while borrowing the core concept: collecting markdown files per PR to document changes.

Prototyping with Test Repositories

At first, I worked on some GitHub Workflows locally, and tested using the GitHub Local Actions VS Code extension, and when I thought I had things working well, I merged some workflows into the WPGraphQL repo, thinking they were in a solid state.

But then… they didn’t run the same in GitHub as they were locally. 😤

I found myself pulling out my hair (or lack thereof) debugging. Instead of continuing to troubleshoot in the main repo, I took a step back and started experimenting in separate repositories to isolate issues and test more freely.

I created multiple test repositories to refine the approach:

1. Automation Tests – My first attempt at testing workflow concepts.

2. Workflow Tests – A fresh start after hitting roadblocks with the initial approach.

3. WPGraphQL Workflow Tests – A fork of WPGraphQL to see how these workflows behaved in a real-world repo structure.

Through trial and error, I was able to pinpoint issues, tweak the workflows, and ultimately get them running smoothly. You can see the results of these manual tests in the workflow test releases.

Once I was confident in the implementation, I merged them back into WPGraphQL, where they successfully generated v2.1.1.

How the Workflows Work

The final implementation consists of two GitHub Actions workflows:

Changeset Generation Workflow

View on GitHub

Runs when a PR is merged into develop
Creates a .changeset/ markdown file documenting the change
Helps maintain a structured history of changes

Release Workflow

View on GitHub

Runs when preparing a new release
Aggregates changesets into a full changelog
Determines the correct version bump (major, minor, patch)
Updates readme.txt with upgrade notices
Publishes the release

Future Automation Plans

Now that the core release process is automated, I’m thinking about how to improve workflows for larger milestone features.

Handling Milestone-Based Feature Work

Some features, like custom scalar support, will require significant iteration before they’re ready to merge and release. My idea is to create a milestone tracking system where:

🚀 Feature branches (feat/email-scalar, feat/datetime-scalar, etc.) merge into milestone branches (milestone/custom-scalars).
📌 Each feature PR generates a changeset, which gets collected in the milestone PR.
🔄 Changes accumulate within a milestone branch, giving visibility into larger features while allowing normal feature releases to continue.
📅 When a milestone is complete, all associated changesets merge into develop, triggering a proper release workflow.

This approach allows larger features to be worked on in parallel while maintaining a clear record of what’s being developed.

I’ll likely experiment with these workflows in the WPGraphQL Workflow Tests repository.

Final Thoughts

Open-source projects like WPGraphQL benefit tremendously from automation. The more we can reduce friction in the development and release process, the better we can focus on delivering new features, improving performance, and maintaining stability.

These workflows have already made releasing WPGraphQL easier, and I’m excited to continue refining them and exploring how we can automate more aspects of feature development and release tracking.

I also want to explore making some of these processes a bit more re-usable so we can easily implement them on some of the other repos, such as: WPGraphQL Smart Cache, WPGraphQL IDE, WPGraphQL for ACF and others.

Who knows, perhaps I may even explore a monorepo setup to see if that could help increase efficiencies for both maintainers and contributors?

If you have thoughts on this approach or ideas for improvements, feel free to reach out on Discord or GitHub! 🚀