# Bumping Version > Inspects, previews, prepares, and direct-pushes approved semantic-version Git commits with consistent manifests and policy-driven changelog updates. Use when the user asks to bump a version, choose patch/minor/major, prepare a release commit, reconcile a release operation, or push an approved version commit to a base branch. Do not use for package-registry publishing, deployment, or tagging an already-versioned commit. - Skill: `ether-moon/bumping-version` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ether-moon/bumping-version` - Raw SKILL.md: https://api.skillmd.com/api/skills/ether-moon/bumping-version/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: ether-moon (https://skillmd.com/u/ether-moon) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/ether-moon/bumping-version --- # Bumping Version Resolve `scripts/release-workflow` relative to the directory containing this `SKILL.md` and invoke that absolute path directly for all inspection and mutation. Do not depend on a host-specific plugin-root environment variable or a shell variable persisting across tool calls. The examples use `` as a non-executable placeholder; replace it with the resolved absolute path in every invocation. The runner reads one immutable base snapshot, isolates preparation from the user's checkout, binds preparation to an accepted preview, and requires separate approval before publication. ## Dependencies and policy The runner preflights Bash 3.2 or newer, `git`, `gh`, and `jq`. Report `MISSING_DEPENDENCY` and stop. It reads the committed `## Versioning` policy from `AGENTS.md` in the base snapshot: - `Base branch` - `Commit message`, with a `{version}` placeholder - `Extra version files`, as comma-separated repository-relative paths - `Changelog categories`, defaulting to `Added, Improved, Fixed` Supported manifests include Claude plugin and package JSON, `pyproject.toml`, `Cargo.toml`, Python `__version__`, gemspecs, Ruby `VERSION`, root `VERSION` and `version.txt`, plus configured extra files. ## Workflow ### 1. Inspect the immutable base Run: ```bash inspect --repo . ``` Pass `--base BRANCH` only when the user selected a base. With `origin`, the runner resolves and fetches its latest exact base SHA. Without `origin`, it uses the committed local base. Dirty files and other local branches never supply release input. Report `base`, `base_sha`, manifests, mismatches, changelog status, policy, and `recent_commits`. Stop on mismatch, unsupported versions, missing manifests, or missing `CHANGELOG.md`; never choose a source of truth silently. ### 2. Preview Recommend a semantic-version level from the inspected commits and ask the user to choose `patch`, `minor`, or `major`. A generic release request is not approval. Run the selected dry preview: ```bash prepare --repo . --level patch --dry-run ``` Preserve an explicit `--base`. For a user-provided changelog entry or commit message, add `--changelog-file PATH` or `--message-file PATH` to both preview and prepare. Relative paths are resolved from the caller directory; the runner owns immutable copies during preparation. Show `base_sha`, `version`, `changed_paths`, `changelog_entry`, `changelog_categories`, and `commit_message`. Retain `base_sha` and `input_digest` exactly; together they identify the accepted preview. ### 3. Prepare with compare-and-swap After the user accepts the preview, run the same arguments without `--dry-run` and add both preview values: ```bash prepare --repo . --level patch \ --expected-base-sha BASE_SHA \ --expected-input-digest INPUT_DIGEST ``` The runner stops before creating a worktree if the remote base, policy, manifests, date, or managed input changed. Otherwise it creates an external temporary worktree and local `release-workflow/release-v...` branch, updates every discovered manifest plus `CHANGELOG.md`, stages only those paths, commits once, and verifies the final commit scope after hooks. Present `base`, `base_sha`, `version`, `commit_sha`, `changed_paths`, and the complete `diff`. Preserve `state_file` and `commit_sha` as publication inputs. ### 4. Ask for publication approval Ask one explicit question in the user's language: ```text Push prepared commit COMMIT_SHA directly to origin/BASE now? ``` If declined, keep the commit and branch but remove the worktree: ```bash cleanup --state-file STATE_FILE --mode declined ``` ### 5. Publish and clean up Only after an affirmative answer, run: ```bash publish --state-file STATE_FILE \ --expected-commit COMMIT_SHA --approve ``` The runner verifies state, origin identity, and remote base SHA before a normal direct push. It never force-pushes or creates a pull request fallback. On success: ```bash cleanup --state-file STATE_FILE --mode success ``` On authentication, protection, or base-race failure, preserve both recovery artifacts: ```bash cleanup --state-file STATE_FILE --mode failure ``` If publication or cleanup completed externally but state persistence failed, retry the same command. The runner reconciles an exact remote commit and already-removed exact worktree or branch idempotently. If the user later requests a pull request, treat that as a new pull-request workflow; do not initiate it here or require another plugin. ## Errors Failures are JSON on stderr with `error.code`, `error.message`, and `error.recovery`. - `BASE_RACE`, `INPUT_CHANGED`: discard the old preview and run a new dry preview. - `VERSION_MISMATCH`, `CHANGELOG_MISSING`: resolve repository content before retrying. - `APPROVAL_REQUIRED`: ask the user; never add approval yourself. - `COMMIT_SCOPE_MISMATCH`, `POST_COMMIT_WORKTREE_DIRTY`: preserve and inspect the isolated branch and worktree. - `PUSH_AUTH_FAILED`, `PUSH_PROTECTED`, `PUSH_FAILED`: report recovery paths and stop. - `STATE_WRITE_FAILED`: restore state-directory writes, then retry the exact publish or cleanup command. Use the user's language for recommendations, approval prompts, errors, and reports. Keep arguments, paths, branch names, and JSON fields unchanged.