174 lines
5.4 KiB
Markdown
174 lines
5.4 KiB
Markdown
---
|
|
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
|