docs(skills): add release workflow skill

This commit is contained in:
xfy 2026-06-05 14:02:20 +08:00
parent 93c0c151d0
commit 989a572467

149
.agents/skills/release.md Normal file
View File

@ -0,0 +1,149 @@
# Skill: 发布新版本
发布 lolly 新版本的完整流程。
## 前置条件
- `gh` CLI 已安装且已认证(`gh auth status`
- `make` 可用
- 工作目录干净(无未提交更改)
## 发布流程
### 1. 确定新版本号
遵循 semver 规范,基于上次 tag 递增:
- PATCHx.y.Zbug 修复、小改进
- MINORx.Y.0):新功能、向后兼容
- MAJORX.0.0):破坏性变更
查看当前版本:
```bash
git tag --sort=-v:refname | head -5
```
### 2. 更新 FALLBACK_VERSION
编辑 `Makefile` 第 4 行,将 `FALLBACK_VERSION` 更新为新版本号(不带 `v` 前缀):
```makefile
FALLBACK_VERSION := x.y.z
```
### 3. 更新 CHANGELOG.md
编辑 `CHANGELOG.md`,将 `[Unreleased]` 下方的内容整理为新版本条目:
```markdown
## [Unreleased]
## [x.y.z] - YYYY-MM-DD
### Added
- ...
### Changed
- ...
### Performance
- ...
### Fixed
- ...
```
保留 `[Unreleased]` 空头,按 Keep a Changelog 格式填写。参考历史条目的分类方式。
### 4. 提交更改
```bash
git add Makefile CHANGELOG.md
git commit -m "chore: release v<x.y.z>"
```
### 5. 质量检查
```bash
make check
```
这会运行 fmt → lint → test-all。确保全部通过后再继续。
### 6. 打 git tag
```bash
git tag v<x.y.z>
```
### 7. 推送
```bash
git push origin main --tags
```
### 8. 交叉编译所有平台
```bash
make build-all
```
产物在 `bin/` 目录:
- `lolly-linux-amd64`
- `lolly-darwin-amd64`
- `lolly-darwin-arm64`
- `lolly-windows-amd64.exe`
- `lolly-freebsd-amd64`
- `lolly-openbsd-amd64`
### 9. 创建 GitHub Release 并上传二进制
使用 `gh` CLI 创建 release 并上传所有二进制文件:
```bash
gh release create v<x.y.z> \
bin/lolly-linux-amd64 \
bin/lolly-darwin-amd64 \
bin/lolly-darwin-arm64 \
bin/lolly-windows-amd64.exe \
bin/lolly-freebsd-amd64 \
bin/lolly-openbsd-amd64 \
--title "v<x.y.z>" \
--notes "$(sed -n '/^## \[x\.y\.z\]/,/^## \[/p' CHANGELOG.md | head -n -1 | tail -n +2)"
```
这会自动从 CHANGELOG.md 提取对应版本的 release notes。
也可以用 `--draft` 先创建草稿,确认无误后再发布:
```bash
gh release create v<x.y.z> ... --draft
gh release edit v<x.y.z> --draft=false
```
### 10.(可选)构建并推送 Docker 镜像
```bash
make docker
make docker-push REGISTRY=<registry>
```
## 检查清单
- [ ] `Makefile``FALLBACK_VERSION` 已更新
- [ ] `CHANGELOG.md` 有新版本条目,日期正确
- [ ] `make check` 全部通过
- [ ] `git tag v<x.y.z>` 已创建
- [ ] tag 和 commit 已推送到 remote
- [ ] `make build-all` 6 个平台二进制编译成功
- [ ] `gh release create` 已发布,二进制已上传
- [ ] 可选Docker 镜像已构建并推送
## 回滚
如果发布有问题,删除 tag 和 release
```bash
gh release delete v<x.y.z> --yes
git push origin :refs/tags/v<x.y.z>
git tag -d v<x.y.z>
```