---
name: release
description: Use when the user asks to release, bump version, update changelog/version files, or commit/push a repository release for the Planet repo. Determines version bump type from changes, updates all required version-bearing files, updates changelog and version-history, runs minimal validation, then commits, tags, and pushes.
---

# Release Workflow

Use this skill for release-oriented work in this repository.

## When To Use

- The user asks to `发版`
- The user asks to bump a version
- The user asks to update `CHANGELOG`, `version-history`, or version files as part of a release
- The user asks to commit/push a release or a publishable bugfix/feature bundle

Do not use this skill for ordinary commits that are not being released.

## Versioning Rules

- `feature` -> bump minor and reset patch to `0` (`x.y.z` → `x.(y+1).0`; for example `0.41.2` → `0.42.0`)
- `bugfix` -> bump `+0.0.1`
- `docs`, `maintenance`, and `refactor` do not bump by default unless the user explicitly wants a release

When intent is mixed, prefer the user's stated release intent.

## Required Files

Use `git rev-parse --show-toplevel` to get the repo root. All paths are relative to it:

- `VERSION`
- `frontend/package.json` (`"version"` field)
- `pyproject.toml` (`version =` field)
- `uv.lock` (**never edit manually** — regenerate by running `uv lock`)
- `docs/CHANGELOG.md`
- `docs/version-history.md`

## Token-Saving Rule

Release work should be driven by deterministic CLI evidence. Prefer compact commands and targeted file reads:

```bash
git status --short
git diff --stat HEAD
git diff --name-only HEAD
rg -n "version|^## |^Released:|current" VERSION frontend/package.json pyproject.toml docs/CHANGELOG.md docs/version-history.md
```

Do not inspect full diffs unless deciding whether changed code belongs in the release.

## Workflow

### Step 1 — Environment check

```bash
git branch --show-current   # must be on dev
git status --short           # check for unrelated uncommitted changes
cat VERSION                  # read current version
```

If not on `dev`, stop and tell the user. Do not proceed.

If unrelated uncommitted changes exist, list them and ask the user whether to include them or stash first.

### Step 2 — Determine release type and next version

- If the user provided an explicit type (`feature` / `bugfix`), use it
- Otherwise infer from `git diff --stat HEAD`, `git diff --name-only HEAD`, focused diffs for changed code, and recent `git log`
- Compute the next version:
  - `feature`: increment minor and reset patch to `0` (e.g. `0.41.2` → `0.42.0`)
  - `bugfix`: increment patch only (e.g. `0.26.2` → `0.26.3`)
- **Show the release plan before making any changes:**

```
Release plan:
  Type:    bugfix
  Version: 0.26.2 → 0.26.3
  Branch:  dev
  Will update: VERSION, frontend/package.json, pyproject.toml, uv.lock, CHANGELOG.md, version-history.md
```

### Step 3 — Update version files

Update in order (use Edit for precise replacement, never rewrite whole files):

1. `VERSION` — replace entire content with new version string
2. `frontend/package.json` — replace `"version": "x.x.x"` line
3. `pyproject.toml` — replace `version = "x.x.x"` line
4. Run `uv lock` at repo root to regenerate `uv.lock`

### Step 4 — Update CHANGELOG.md

Insert a new entry at the top of the file:

```markdown
## x.x.x

Released: YYYY-MM-DD

### Highlights

- ...

### Added / Fixed / Improved

- ... (high-signal items only, max 5)

---
```

Get today's date with `date +%Y-%m-%d`.

### Step 5 — Update docs/version-history.md

- Update the "current dev version" field in the file header
- Insert a new row at the top of the timeline table: `| vx.x.x | YYYY-MM-DD | one-line summary |`

### Step 6 — Validate

Run the smallest relevant validation for the changes in scope:

- Python files changed: list changed Python files with `git diff --name-only HEAD -- '*.py'`, then run `python3 -m py_compile <changed_files>`
- Frontend files changed: list changed frontend files with `git diff --name-only HEAD -- frontend`, then run the project-standard check if available; otherwise skip and say so
- Version consistency: confirm VERSION, package.json, pyproject.toml, and uv.lock all show the same version

```bash
cat VERSION
rg -n "\"version\":|^version =|version = " frontend/package.json pyproject.toml uv.lock
```

### Step 7 — Pre-commit preview

Show what will be committed:

```bash
git diff --stat HEAD
```

Confirm all required files are present and no unexpected files (debug files, `.env`, etc.) are included.

### Step 8 — Commit, tag, and push

```bash
git add VERSION frontend/package.json pyproject.toml uv.lock docs/CHANGELOG.md docs/version-history.md
# also stage any code changes included in this release
git add <code_files>

git commit -m "release: bump version to x.x.x"
git tag vx.x.x
git push origin dev
git push origin vx.x.x
```

Commit message format is fixed: `release: bump version to x.x.x`

### Step 9 — Completion summary

```
✓ Version bumped: 0.26.2 → 0.26.3
✓ CHANGELOG updated
✓ version-history updated
✓ uv.lock regenerated
✓ Validation passed
✓ commit: release: bump version to 0.26.3
✓ tag: v0.26.3
✓ Pushed to origin/dev
```

## Notes

- `uv.lock` must only be updated by running `uv lock`, never manually
- The release commit should include only version files + the code for this release — no unrelated changes
- If `uv` is unavailable in the environment, say so explicitly and remind the user to run it manually