diff --git a/skills/gitlink-release-auto/SKILL.md b/skills/gitlink-release-auto/SKILL.md new file mode 100644 index 0000000..6200905 --- /dev/null +++ b/skills/gitlink-release-auto/SKILL.md @@ -0,0 +1,287 @@ +--- +name: gitlink-release-auto +version: 1.0.0 +description: "自动化 Release 管理：从提交历史自动生成 Release Notes、推荐语义化版本号、批量发布管理。当用户需要创建版本发布、生成更新日志、自动化发版流程时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli release --help" +--- + +# gitlink-release-auto（自动化 Release 管理） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — `release +view` 必须使用 `version_id`（从 `release +list` 返回），不能用 tag_name，否则返回 HTML 页面而非 JSON。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) + +--- + +## 功能概述 + +本技能提供完整的自动化发版流程： + +1. **语义化版本推荐** — 根据提交类型自动推荐下一个版本号 +2. **Release Notes 自动生成** — 从提交历史和已关闭 Issue 自动生成 Changelog +3. **一键发布** — 创建 Release 并关联 Tag +4. **发布后通知** — 在相关 Issue 中关联发版信息 + +--- + +## 一、版本号推荐（Semantic Versioning） + +### Semver 规则 + +``` +v.. + +MAJOR：有 Breaking Change（不向下兼容的变更） +MINOR：有 feat（新增功能，向下兼容） +PATCH：只有 fix / perf / refactor / docs 等修复性变更 +``` + +### 步骤 1：获取当前版本号 + +```bash +# 获取最新 Release（从中找当前版本号） +gitlink-cli release +list --owner --repo --format json +# 取 data.releases[0].tag_name 作为当前版本 + +# 获取标签列表 +gitlink-cli api GET /:owner/:repo/tags --format json +``` + +### 步骤 2：获取自上次发版以来的提交 + +```bash +# 获取自上次 Release 以来的提交 +git log v1.1.0..HEAD --format="%H %s %an %ad" --date=short 2>&1 +``` + +### 步骤 3：AI 分析提交类型，推荐版本号 + +根据提交信息（Conventional Commits）进行分类： + +``` +决策逻辑： +1. 任意提交包含 "BREAKING CHANGE" → MAJOR 升级 + 当前 v1.2.3 → 推荐 v2.0.0 + +2. 有 feat: 类型的提交（且无 Breaking Change）→ MINOR 升级 + 当前 v1.2.3 → 推荐 v1.3.0 + +3. 仅有 fix/perf/refactor/docs/chore/ci 类型 → PATCH 升级 + 当前 v1.2.3 → 推荐 v1.2.4 +``` + +**版本号推荐输出示例：** + +``` +当前版本：v1.2.3 +分析了 18 次提交（2026-04-15 至今）： + - 3 个 feat：新增用户头像、搜索历史、消息通知 + - 5 个 fix：修复了 5 个 Bug + - 2 个 docs：更新了接口文档 + - 无 Breaking Change + +推荐版本：v1.3.0（MINOR 升级，有新功能） +备选版本：v1.2.4（如果认为功能较小，可用 PATCH） +``` + +--- + +## 二、Release Notes 自动生成 + +### 获取数据 + +```bash +# 1. 获取自上次 Release 以来的提交 +git log v1.1.0..HEAD --format="%H %s %an %ad" --date=short 2>&1 + +# 2. 获取本期关闭的 Issue +gitlink-cli issue +list --state closed --owner --repo --format json + +# 3. 获取本期合并的 PR 列表 +gitlink-cli pr +list --state merged --owner --repo --format json +``` + +### Release Notes 模板 + +```markdown +## v1.3.0 (2026-05-07) + +### ✨ 新功能 + +- feat(user): 新增用户头像上传功能 ([#234](link)) +- feat(search): 支持全文搜索和历史记录 ([#256](link)) +- feat(notify): 添加站内消息通知系统 ([#267](link)) + +### 🐛 Bug 修复 + +- fix(login): 修复手机号登录时验证码未清除的问题 ([#245](link)) +- fix(upload): 修复大文件上传超时问题 ([#251](link)) +- fix(api): 修复并发请求时偶发 500 错误 ([#259](link)) + +### ⚡ 性能优化 + +- perf(search): 优化搜索接口响应速度，平均提升 40% ([#261](link)) + +### 📦 其他变更 + +- docs: 更新 API 接口文档 +- build: 升级 Go 依赖到最新版本 +- ci: 添加代码覆盖率检查 + + +### 🤝 贡献者 + +感谢以下贡献者参与本版本开发：@zhangsan、@lisi、@wangwu + +``` + +--- + +> ⚠️ **重要**：`贡献者` 必须去重！release notes中如果有相同或者相似的记录，需要去重！不需要添加`完整变更日志`这个信息！ + + +## 三、一键发布完整流程 + +### 标准发版步骤 + +```bash +# Step 1：确认当前版本和推荐版本 +gitlink-cli release +list --owner --repo --format json + +# Step 2：获取变更内容（提交历史） +gitlink-cli api GET /:owner/:repo/commits --query 'page=1&limit=30&ref=master' --format json + +# Step 3：生成 Release Notes（AI 分析提交后组织内容） + +# Step 4：创建 Release +gitlink-cli release +create \ + --owner \ + --repo \ + --tag v1.3.0 \ + --name "v1.3.0 - 用户体验升级版" \ + --body "## v1.3.0\n\n### ✨ 新功能\n- ...\n\n### 🐛 Bug 修复\n- ..." \ + --target master + +# Step 5：验证发布成功 +gitlink-cli release +list --owner --repo --format json +# 从列表取 version_id + +gitlink-cli release +view --owner --repo --id +``` + +> ⚠️ **重要**：`release +view` 必须用 `version_id`（整数），不能用 tag 名称（如 v1.3.0） + +### 预发布版本 + +```bash +# 创建 alpha/beta/rc 预发布版本 +gitlink-cli release +create \ + --tag v1.3.0-beta.1 \ + --name "v1.3.0 Beta 1" \ + --body "预发布版本，用于测试..." \ + --prerelease true \ + --target develop +``` + +--- + +## 四、发布后操作 + +### 关联 Issue 通知 + +```bash +# 在关联的 Issue 中添加评论，通知已发版 +gitlink-cli issue +comment \ + --id \ + --body "🎉 此问题已在 v1.3.0 中修复，请更新到最新版本验证。" +``` + +### 批量关联 Issue + +```bash +# 遍历本期关闭的 Issue，逐一添加发版通知评论 +gitlink-cli issue +list --state closed --format json +# 对每个 issue_id 执行 issue +comment +``` + +### 触发部署（可选） + +```bash +# 发版后触发部署（通过 CI 重新构建 tag 对应的分支） +gitlink-cli ci +restart --build +``` + +--- + +## 五、完整发版检查清单 + +在执行发版前，确认以下事项： + +``` +发版前检查： +□ 所有计划纳入本次版本的 PR 已合并 +□ CI 在 master 分支的最新构建是成功的 +□ 所有计划修复的 Issue 已关闭 +□ 文档已更新（README、API 文档等） +□ 数据库迁移脚本已准备就绪（如有） + +版本号确认： +□ 版本号遵循 Semantic Versioning +□ 是否有 Breaking Change（需 MAJOR 升级） +□ 是否发预发布版本（alpha/beta/rc） + +Release Notes 检查： +□ 新功能描述清晰 +□ Bug 修复有具体说明 +□ Breaking Change 有迁移指南 +□ 关联了对应的 Issue / PR 链接 + +发版操作： +□ 在正确的分支/提交上打 Tag +□ Release 创建成功 +□ 相关 Issue 已通知 +``` + +--- + +## 六、版本管理最佳实践 + +### 发版节奏建议 + +| 模式 | 说明 | 适用场景 | +|------|------|---------| +| 定期发版 | 每 1~2 周一次 PATCH，每月一次 MINOR | 功能迭代稳定的项目 | +| 功能发版 | 功能完成即发版 | 需求驱动、快速迭代 | +| 按需发版 | Bug 修复立即发版 | 线上紧急修复（hotfix） | + +### Hotfix 发版流程 + +```bash +# 1. 从当前 Release Tag 创建 hotfix 分支 +gitlink-cli branch +create --name hotfix/v1.2.4-critical-fix --from v1.2.3 + +# 2. 在 hotfix 分支修复问题，合并回 master +# （通过 PR 流程） + +# 3. 快速发布 PATCH 版本 +gitlink-cli release +create \ + --tag v1.2.4 \ + --name "v1.2.4 紧急修复版" \ + --body "## 紧急修复\n\n- fix: 修复生产环境关键 Bug（#xxx）" \ + --target master +``` + +--- + +## 注意事项 + +- ✅ **版本号一旦发布不可修改**，确认无误后再执行创建 +- ✅ **BREAKING CHANGE 必须在 Release Notes 中明确标注**，并提供迁移指南 +- ⚠️ **`release +view` 始终使用 `version_id`** +- ✅ **预发布版本（beta/rc）先内部测试**，验证后再发正式版 +- ✅ **发版后通知**，注意发版后，要对所有关联的issue添加通知评论