wp-plugin-release

name

wp-plugin-release

description

Use when bumping a WordPress plugin version or cutting a release — syncing version across all sources: plugin header (Version: X.Y.Z), version constant (define MY_PLUGIN_VERSION), readme.txt (Stable tag + Changelog + Upgrade Notice), CHANGELOG.md, and .pot Project-Id-Version; following semver (major/minor/patch) rules; running pre-release checks (composer lint / analyze / test, grep for stale version strings); creating a git tag; and deciding what NOT to bump (DB schema version, historical changelog entries). Triggers: "release version 1.2.3", "bump the version", "update the changelog", "sync version numbers", "prepare the release", "tag this version", "version is out of sync", "update Stable tag", "what needs to change for a release", "changelog entry", "update readme.txt version", "bump to 2.0.0", "Version header in plugin file", "define MY_PLUGIN_VERSION", "semver patch vs minor vs major", "Project-Id-Version in POT", "grep for old version strings", "git tag for release", "Upgrade Notice section", "what to bump vs not bump". Not for: WP.org SVN deploy or first-time submission — use `wp-org-submission`.

WordPress Plugin Release / Version Sync

Model note: Mechanical file edits — works well on haiku. No reasoning across ambiguous code; all sources are explicit (header, constant, readme.txt, changelog).

Bump a WP plugin version coherently. Prevents the classic drift where the plugin header says one version, the readme.txt Stable tag another, and the .pot a third.

When to use

• "Release X.Y.Z", "bump the version", "update the changelog / readme.txt".
• After substantial work has landed under an unreleased version.

Not for: WP.org SVN deploy (trunk/tags/assets push) — use wp-org-submission. First-time plugin submission to the WP.org directory — use wp-org-submission.

First: determine the real current state

git tag                       # any release tags?
gh release list               # any published releases?
grep -n "Version:" *.php       # plugin header
grep -n "_VERSION'" *.php       # version constant
grep -n "Stable tag" readme.txt

If header/constant/Stable-tag disagree, that drift IS the problem — pick the target version and sync all of them. Choose the bump by semver: new backward-compatible features → minor; fixes only → patch; breaking → major. Internal-only refactors (dir rename) don't force a major.

Sources to update (all, in lockstep)

1. Plugin header * Version: X.Y.Z (main plugin file).
2. Version constant define( 'PLUGIN_VERSION', 'X.Y.Z' ).
3. readme.txt Stable tag: X.Y.Z — and Tested up to / Requires PHP if they changed.
4. readme.txt Changelog — add a = X.Y.Z = block listing what shipped (security, features, fixes), grouped.
5. readme.txt Upgrade Notice — add = X.Y.Z = one-liner (why upgrade).
6. .pot — regenerate so Project-Id-Version matches and new strings are captured:

   composer makepot           # or: wp i18n make-pot . languages/<slug>.pot --exclude=...
   

Do NOT bump

• Schema / DB version (e.g. LicenseModel::$db_version) — independent of plugin version. Only bump when the table actually changed, since it gates data migrations.
• Historical changelog entries or point-in-time docs.

Verify

composer lint && composer analyze && composer test
grep -rn "X\.Y\.Z\|<old version>" --include=*.php --include=readme.txt .   # confirm sync, spot stragglers

Then commit (docs:/chore: for a pure version+readme bump), and ship via the repo's contribution flow (branch → PR → merge; never squash if the repo says so).

References

• references/readme-txt-skeleton.txt — full WP.org readme.txt skeleton (all sections) with the release-sync checklist of every version source baked in as a trailing comment.
• references/release-checklist.md — pre-release checklist: code, version sync, changelog, zip hygiene, and post-release verification steps
• references/svn-deploy.md — SVN deploy workflow: initial checkout, trunk update, assets directory, tagging a release, and Stable tag mechanics