planet/.codex/skills/release/SKILL.md

name, description

name	description
release	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

Workflow

Step 1 — Environment check

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 HEAD 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:

## 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: python3 -m py_compile <changed_files>
• Frontend files changed: 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

grep -h "version" VERSION frontend/package.json pyproject.toml

Step 7 — Pre-commit preview

Show what will be committed:

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

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