---
name: gitlink-release-auto
version: 2.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 — GitLink 操作只能用 `gitlink-cli`。**

---

## 功能概述

本技能提供完整的自动化发版流程：

1. **语义化版本推荐** — 根据提交类型自动推荐下一个版本号
2. **Release Notes 自动生成** — 从提交历史分析、归类、统计，生成结构化 Changelog
3. **变更影响分析** — 统计变更文件数、新增/删除行数、涉及模块
4. **一键发布** — 创建 Release 并关联 Tag

---

## 数据分析流程

### Step 1：获取基线版本

```bash
# 获取最新 Release 确定基线
gitlink-cli release +list --owner myuser --repo myrepo --format json
```

**分析输出：** 提取最新 tag_name（如 v1.2.0）作为对比基准。

### Step 2：分析提交历史

```bash
git log v1.2.0..HEAD --format="%H|%s|%an|%ad" --date=short --stat
```

**分析逻辑：**

对每条 commit 的 message 进行分类统计：

```
feat:      → ✨ 新功能
fix:       → 🐛 Bug 修复
docs:      → 📝 文档更新
refactor:  → ♻️ 代码重构
perf:      → ⚡ 性能优化
test:      → ✅ 测试相关
chore:     → 🔧 工程配置
revert:    → ⏪ 回退
其他       → 📦 其他变更
```

**统计维度：**

```
总提交数 = feat + fix + docs + refactor + perf + test + chore + 其他
涉及文件 = git log --stat 统计的总文件数
变更行数 = git log --stat 统计的 +行/-行
贡献者数 = unique author 数量
```

### Step 3：语义化版本推荐规则

```
根据 commit 类型判断版本号变更幅度：
- 含有 BREAKING CHANGE 或 feat! → 主版本号 +1（v1.x.x → v2.0.0）
- 含有 feat 且无 breaking     → 次版本号 +1（v1.2.x → v1.3.0）
- 只有 fix/refactor/docs 等   → 修订号 +1（v1.2.0 → v1.2.1）

推荐版本号：v{major}.{minor}.{patch}
```

### Step 4：生成结构化的 Release Notes

```markdown
## v1.3.0 (2026-06-17)

### 📊 版本概览
- 包含 **{total_commits}** 次提交
- 涉及 **{total_files}** 个文件
- 新增 **{additions}** 行 / 删除 **{deletions}** 行
- 贡献者：**{contributors}** 人

### ✨ 新功能（{feat_count}）
- feat: 新增代码片段管理功能（@author）
- feat: 新增 Webhook 投递监控（@author）

### 🐛 Bug 修复（{fix_count}）
- fix: 修复 Wiki 删除时侧边栏残留问题（@author）

### 📝 文档（{docs_count}）
- docs: 更新 Shortcut 实现报告（@author）
- docs: 添加工作流示例（@author）

### 🔧 工程（{chore_count}）
- chore: 添加 DevOps CI 流水线（@author）

### ⚡ 性能优化（{perf_count}）
- perf: 优化 hook-runner 输出格式（@author）

### ⏪ 回退（{revert_count}）
- revert: 移除 Sidebar 自动管理（@author）

### 📈 统计汇总
| 类别 | 数量 | 占比 |
|------|------|------|
| ✨ 新功能 | {feat_count} | {feat_percent}% |
| 🐛 修复 | {fix_count} | {fix_percent}% |
| 📝 文档 | {docs_count} | {docs_percent}% |
| 🔧 工程 | {chore_count} | {chore_percent}% |
| ♻️ 重构 | {refactor_count} | {refactor_percent}% |
```

### Step 5：创建 Release

```bash
gitlink-cli release +create --owner myuser --repo myrepo \
  --tag v1.3.0 \
  --name "v1.3.0" \
  --body "生成的 Release Notes 内容" \
  --target master
```

---

## 完整示例

假设项目当前 tag 为 v1.2.0，执行：

```bash
# 获取基线
gitlink-cli release +list --owner myuser --repo myrepo --format json

# 获取提交历史
git log v1.2.0..HEAD --format="%H|%s|%an|%ad" --date=short

# 分析结果示例：
# 共 12 次提交：feat 3、fix 2、docs 4、chore 2、perf 1
# 涉及 18 个文件，+350/-120 行
# 3 位贡献者
# 推荐版本：v1.3.0（有 feat，无 breaking）

# 生成的 Release Notes：
```

```markdown
## v1.3.0 (2026-06-17)

### 📊 版本概览
- 包含 **12** 次提交 | 涉及 **18** 个文件
- 新增 **+350** 行 / 删除 **-120** 行
- 贡献者：**3** 人

### ✨ 新功能（3）
- feat: 新增代码片段管理
- feat: 新增 Webhook 投递监控
- feat: 新增 Wiki 管理 Skill

### 🐛 Bug 修复（2）
- fix: 修复 _Sidebar.md 残留问题
- fix: 修复 snippet delete API 参数错误

### 📝 文档（4）
- docs: 添加工作流示例
- docs: 更新实现报告

### 🔧 工程（2）
- chore: 添加 CI 流水线
- chore: 更新依赖

### ⚡ 性能优化（1）
- perf: 优化 list 输出格式

### 📈 统计汇总
| 类别 | 数量 | 占比 |
|------|------|------|
| ✨ 新功能 | 3 | 25% |
| 🐛 修复 | 2 | 17% |
| 📝 文档 | 4 | 33% |
| 🔧 工程 | 2 | 17% |
| ⚡ 性能 | 1 | 8% |
```

```bash
# 创建 Release
gitlink-cli release +create --owner myuser --repo myrepo \
  --tag v1.3.0 --name "v1.3.0" --body "生成的 Release Notes" --target master
```

## 注意事项

- 每个分类都要统计**数量**和**占比**，让读者直观了解本次发布的构成。
- commit message 必须遵循 Conventional Commits 规范才能正确分类（`feat:` / `fix:` / `docs:` 等）。
- 对于不符合规范的 commit，归类为"📦 其他变更"。
- 如果包含 BREAKING CHANGE，务必提示版本号升级的影响。
