iflow-version-bump

name	iflow-version-bump
description	Bump the project version following the project's release strategy: static pyproject versions via uv, or tag-derived versions via a planned git tag.
disable-model-invocation	true
issue-flow-version	0.4.2a4

issue-flow — version bump

Use this skill to bump the project version before landing work (often invoked from /iflow-close) — either at a specific level, or with the default rule below when none is given. What "bump" means depends on the release strategy, so resolve that first.

MODEL & EXECUTION DIRECTIVE

Profile: economy — Prioritize speed and token economy over deep reasoning.

In Cursor: use Auto or a fast model before invoking this step.

Keep scope tight to what this step requires.

CLI fast path (optional). If the issue-flow CLI is on PATH, run issue-flow agent version-plan [--bump <level>] --json. It detects the strategy from pyproject.toml, reads the latest tag, does the PEP 440 next-version arithmetic, and returns the exact commands — read-only, it never edits files or creates tags. The this-project.md release section still wins over its detection: when the payload says brief_release_section: "filled", read the section and follow it. If the CLI is missing or errors, fall back to the manual steps below.

Resolve the release strategy first

In order — stop at the first that answers:

1. .issueflows/04-designs-and-guides/this-project.md — if its "Release & version bump" section is filled in, follow it verbatim. It is the project's own documentation and beats every default below.
2. Detect from pyproject.toml:
   • dynamic = ["version"] under [project], together with a tag-driven backend ([tool.setuptools_scm], hatch-vcs in the build requires, versioningit, or similar) → git-tag derived strategy.
   • a static version = "..." under [project] → static version (uv) strategy.
3. Neither (no pyproject.toml, or no version at all) → skip the bump, explain why, and continue the rest of the flow (for example /iflow-close) without failing.

Record what you learn (self-healing). When the strategy came from detection or from the user explaining it — i.e. not from this-project.md — add or fill in the "Release & version bump" section of .issueflows/04-designs-and-guides/this-project.md with a short description of the strategy and the exact commands, so no future session has to rediscover it. The brief is user-owned and never overwritten by issue-flow update, so the note is durable.

Bump levels (both strategies)

Every level below is allowed; the same table drives both strategies (examples from 0.4.1a4):

Level	Effect
major	1.0.0
minor	0.5.0
patch	0.4.2
stable	0.4.1 — drop the pre-release/dev segment
alpha	0.4.1a5 — next alpha pre-release
beta	0.4.1b1 — promote/advance to beta
rc	0.4.1rc1 — promote/advance to release candidate
post	0.4.1a4.post1 — post-release
dev	dev release — must be paired with another component

Choosing the level

1. The user named a level (patch, minor, major, stable, alpha, beta, rc, post, dev) → use exactly that.
2. The user asked to bump/release but gave no level → apply the pre-release-aware default, based on the current version (static field, or latest tag):
   • current is an alpha (aN) → next alpha
   • current is a beta (bN) → next beta
   • current is a release candidate (rcN) → next rc
   • current is a dev release (.devN) → advance dev paired with the component being advanced (default patch)
   • current is a stable release (no pre-release segment) → patch
3. Free-text intent (e.g. "bugfix release", "promote to beta") → map to the matching level (bugfix → patch, "to beta" → beta); if genuinely ambiguous, ask once rather than guessing major.

Strategy: static version (uv)

For a Python + uv project whose pyproject.toml has a [project] version field.

1. Run from the project root (the directory that contains pyproject.toml).
2. Use only uv with --bump <level>:

uv version --bump patch     # 0.4.1a4 -> 0.4.2
uv version --bump alpha     # 0.4.1a4 -> 0.4.1a5
uv version --bump minor --bump alpha   # combine: 0.4.1a4 -> 0.5.0a1

Tip: preview without writing using uv version --dry-run --bump <level> --short.

3. Afterwards: confirm the new version in pyproject.toml (or the uv output). When committing later, stage pyproject.toml; if uv.lock changed as well, stage it too — otherwise do not assume it changed.

Strategy: git-tag derived

For projects whose built version comes from the latest git tag (setuptools-scm, hatch-vcs, versioningit, …). Here bumping means planning a tag, and the tag is created after the PR merges — never before.

1. Never edit a version into pyproject.toml — the backend derives it.
2. Find the current version: latest tag via git describe --tags --abbrev=0 (or git tag --sort=-v:refname and take the first). Keep the project's existing tag style (e.g. a leading v).
3. Compute the planned next version from the level table above (e.g. latest v1.0.4a2 + alpha → planned v1.0.4a3).
4. Do not create the tag during /iflow-close. In a squash-merge world the issue-branch commit never lands on the default branch, so a pre-merge tag would point at an orphan. Instead:
   • report the planned tag in the close output and record it in the issue's status file,
   • let HISTORY.md promotion use the planned version,
   • create the tag after the merge, standing on the updated default branch (this is offered by /iflow-cleanup, or happens right after the post-merge pull in a yolo close):

git tag v1.0.4a3
git push origin v1.0.4a3
# or, to also cut a GitHub release:
gh release create v1.0.4a3 --generate-notes

Constraints

• Do not substitute pip or hand-edit versions unless the strategy's own tool fails and the user agrees to an alternative.
• Never silently jump release channels: don't promote an alpha to stable (or bump major/minor) just because no level was given — the default keeps you on the current pre-release channel.
• Tag-derived projects: never tag an issue-branch commit; the tag is created on the merged default branch only.