Case Studies WP Plugin Version Guard: a CI gate for version drift
WP Plugin Version Guard: a CI gate for version drift
TL;DR A WordPress plugin states its version in several places: the header, readme.txt, a constant, and the changelog. They drift out of sync and ship broken. WP Plugin Version Guard is a GitHub Action that fails CI when those versions disagree, catching the mistake before release.
Releasing a WordPress plugin has a small, recurring trap: the version number lives in several files, and if they disagree, the release misbehaves. I hit it enough times that I built a CI check to catch it. WP Plugin Version Guard is that check.
The problem
A plugin declares its version in more than one place.
- The plugin header is what WordPress reads.
- The readme.txt Stable tag tells the plugin directory which version is current.
- A version constant in the code is what the plugin uses internally.
- The changelog records what shipped.
They all have to say the same thing. Update the header for a release but forget the readme Stable tag, and the directory serves the wrong version and updates break. It is an easy mistake to make by hand and an annoying one to debug after release.
The approach
The fix belongs in CI, where it runs automatically and blocks a bad release.
- Read the version from every place it is declared: header, readme, constant, changelog.
- Compare them. If any disagree, fail the check.
By running in the pull request, it catches the drift before merge, when fixing it is trivial, rather than after release, when it is a support problem.
What shipped
WP Plugin Version Guard is a GitHub Action that fails CI when a plugin's version is out of sync across the header, readme.txt, a constant, and the changelog. Drop it into a workflow and the release trap becomes a caught error in the pull request instead of a broken update in the wild.
What I learned building it
The lesson was that the most valuable automation often guards a boring, avoidable mistake. Nobody means to ship mismatched versions; they just forget one file among four. A check that makes that impossible to merge is worth far more than its few lines suggest. It is the same instinct behind my WP Plugin CI Action: let the machine enforce the tedious consistency so a human never has to remember it.
WP Plugin Version Guard is free on the GitHub Marketplace, and its source is on my GitHub.
FAQ
Why does a plugin version live in multiple places?
WordPress reads the version from the plugin header, the readme.txt Stable tag tells the directory which version is current, code often defines a version constant, and the changelog records it. Each serves a purpose, but keeping four copies in step by hand is error-prone.
What goes wrong when they drift?
Users can be served the wrong version, update notices misfire, and the changelog no longer matches the code. A mismatch between the header and the readme Stable tag is a classic way to ship a release that does not update cleanly.
How does the Action prevent it?
It runs in CI and compares the version across the header, readme.txt, the constant, and the changelog. If any disagree, the check fails, so the mismatch is caught in the pull request instead of after release.