wp-bump

WP Bump

When to use

Use this skill when:

• Performing a plugin release bump with coordinated version updates across existing files.
• Generating release notes from commit history and writing them to available changelog locations.
• Running the project’s existing build and validation commands as a release gate.

Inputs required

• Repo root (current working directory).
• Target version, preferably SemVer (1.2.3). If missing, ask the user.
• Changelog entry: auto-derived from git log since the last tag; prompt only if no useful commits are found.
• Release date. Default to today’s date.

Determinism checklist

Apply DETERMINISM-CHECKLIST.md for this skill run.

Do not create commits, tags, or releases unless the user explicitly asks.

Procedure

0) Inspect project state

Before editing, check for existing user changes and project files:

git status --short

Detect the main plugin file by scanning root-level PHP files for a Plugin Name: header. If multiple files match, ask the user which one to update.

Gather commits since last release

Find the most recent tag and collect commit subjects since then:

git tag --sort=-creatordate | head -1          # latest tag, empty if none
git log <last-tag>..HEAD --oneline --no-merges # commits since last tag

If there is no tag yet, use git log --oneline --no-merges (all commits).

Store these subjects as candidate changelog lines. Filter out noise: commits whose subject starts with Merge, Revert, chore:, ci:, build:, style:, or is identical to the bump commit itself. If any candidate lines remain, use them to draft the changelog entry (see step 3). Only prompt the user for changelog content when no useful commits are found after filtering.

Inspect these files if they exist:

• Main plugin file (Version: header)
• readme.txt (Stable tag: and == Changelog ==)
• package.json (version field and available scripts)
• package-lock.json or npm-shrinkwrap.json
• composer.json (available scripts)
• CHANGELOG.md

Completion criterion: Current version sources and candidate changelog commits are collected before any edits.

1) Validate the target version

Use a plain version string without a leading v in project files. If the user provides v1.2.3, write 1.2.3.

Confirm the target version is newer than the current plugin header version when both are valid SemVer values. If the target version is not newer, ask before continuing.

Completion criterion: Target version format and upgrade direction are validated, and any non-increasing bump is explicitly user-approved.

2) Bump version fields

Update all version fields that exist in the project:

• Main plugin file: update the header line matching Version:.
• readme.txt: update Stable tag: to the target version.
• package.json: update version if the file exists.

For package.json, prefer the package manager when lockfiles exist:

npm version <target-version> --no-git-tag-version

If there is no npm lockfile, it is acceptable to edit package.json directly as structured JSON. Do not create package.json only for a version bump.

Completion criterion: All existing version fields match the target version.

3) Update changelogs

Draft the changelog entry

Use the candidate commit subjects collected in step 0 to draft bullet points:

• Strip conventional-commit prefixes (fix:, feat:, docs:, etc.) and capitalise the first letter.
• One bullet per subject line.
• Present the draft to the user for confirmation or editing before writing files.
• If no candidates were found, prompt the user for concise release notes.

Hard gate: Do not write changelog files until the draft entry is confirmed by the user.

Update both changelog locations.

CHANGELOG.md

If CHANGELOG.md exists, insert a new release section near the top, below the title and optional Unreleased section:

## <target-version> - YYYY-MM-DD

- Release note.

If the project already follows a different changelog style, preserve that style. If CHANGELOG.md does not exist, create it with:

# Changelog

## <target-version> - YYYY-MM-DD

- Release note.

readme.txt

In readme.txt, insert the release entry directly under == Changelog ==:

= <target-version> =
* Release note.

Preserve the existing WordPress.org readme format. If readme.txt does not exist, skip it and report that it was absent.

Completion criterion: Changelog entry exists in every available changelog location with consistent version/date.

4) Rebuild

Run the project’s build step if one exists.

For npm projects:

npm run build --if-present

If dependencies are missing and the project has a lockfile, install them with the matching package manager before rebuilding. Do not add new dependencies as part of a version bump unless the user explicitly asks.

For Composer-only projects, run the relevant generated/build script only if it exists in composer.json.

Completion criterion: Existing build command(s) completed or the exact skip reason was reported.

5) Run tests and checks

Run available tests. Use scripts already defined by the project; skip missing scripts cleanly.

Recommended order:

composer validate --no-check-publish
composer run test
composer run lint
npm test --if-present
npm run test:js --if-present

If the project has a plugin-check script, run it when the local WordPress/WP-CLI environment is available:

composer run check

Report any command that could not run because a tool, dependency, or local WordPress environment was missing.

Completion criterion: Every available check command was run in order, with pass/fail/skip status captured.

6) Final review

Review the diff before responding:

git diff --stat
git diff --check

In the final response, include:

• Files changed.
• Version bumped from/to, when known.
• Changelog entry added.
• Rebuild command result.
• Test/check command results.
• Any skipped files or commands and why.

Completion criterion: Diff review completed and final report includes all required release details.

Failure modes / debugging

• No plugin file found: ask for the main plugin file path.
• Multiple plugin files found: ask which plugin header should be bumped.
• Version mismatch after edits: re-open the plugin file, readme.txt, and package.json; all existing version fields must match the target version.
• npm version fails: inspect package.json for invalid JSON or workspace/package-manager constraints.
• Build/test fails: stop after collecting the failure output and report the failing command with the relevant error summary.

📦 Source: soderlind/skills · Edit on GitHub