From 989a572467e15bf5329b77516b1cc1aa6470eeea Mon Sep 17 00:00:00 2001
From: xfy <i@rua.plus>
Date: Fri, 5 Jun 2026 14:02:20 +0800
Subject: [PATCH] docs(skills): add release workflow skill

---
 .agents/skills/release.md | 149 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 .agents/skills/release.md

diff --git a/.agents/skills/release.md b/.agents/skills/release.md
new file mode 100644
index 0000000..15377d3
--- /dev/null
+++ b/.agents/skills/release.md
@@ -0,0 +1,149 @@
+# Skill: 发布新版本
+
+发布 lolly 新版本的完整流程。
+
+## 前置条件
+
+- `gh` CLI 已安装且已认证（`gh auth status`）
+- `make` 可用
+- 工作目录干净（无未提交更改）
+
+## 发布流程
+
+### 1. 确定新版本号
+
+遵循 semver 规范，基于上次 tag 递增：
+- PATCH（x.y.Z）：bug 修复、小改进
+- MINOR（x.Y.0）：新功能、向后兼容
+- MAJOR（X.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>
+```