---
name: gitlink-changelog
version: 1.0.0
description: "Release Notes 生成：根据 commit 和 PR 记录自动生成结构化版本发布说明。当用户需要生成 Release Notes、发版说明时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli release --help"
---

# gitlink-changelog（Release Notes 生成）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。

## 工作流

Release Notes 生成分三步：收集 → 分类 → 发布。

| 步骤 | 说明 | 所用命令 |
|------|------|----------|
| 1. 收集数据 | 获取版本间的 commits、已合并 PR、已关闭 Issue | `release +list`, `api GET compare`, `pr +list`, `issue +list` |
| 2. 分类整理 | 按类型归类变更（新功能/Bug修复/改进/破坏性变更） | AI 分析 |
| 3. 生成发布 | 套用模板生成 Notes，创建或更新 Release | `release +create`, `release +update` |

## 命令参考

### 收集数据

```bash
# 确定版本范围：获取已有 release 列表，找上一个 tag
gitlink-cli release +list --format json

# 获取两个版本间的 commit 差异（平台 compare API）
gitlink-cli api GET /:owner/:repo/compare/v1.0.0...v1.1.0 --format json

# 获取已合并的 PR
gitlink-cli pr +list --state merged --format json

# 获取已关闭的 Issue
gitlink-cli issue +list --state closed --format json
```

### 发布 Release Notes

```bash
# 创建 Release 并附带 Notes
gitlink-cli release +create --tag v1.1.0 --name "v1.1.0" --body "<Markdown 格式的 Release Notes>"

# 更新已有 Release 的 Notes
gitlink-cli release +update --id <version_id> --body "<更新后的 Notes>"
```

## 分类规则

| 类型 | 图标 | Issue 标签 | Commit 关键词 |
|------|------|------------|---------------|
| 新功能 | ✨ | `feature`, `enhancement` | `feat:`, `add`, `新增` |
| Bug 修复 | 🐛 | `bug`, `fix` | `fix:`, `bugfix`, `修复` |
| 功能改进 | 🔧 | `improvement`, `optimize` | `improve:`, `optimize:`, `refactor:` |
| 破坏性变更 | ⚠️ | `breaking`, `major` | `BREAKING`, `breaking:`, `!` |
| 文档 | 📝 | `docs`, `documentation` | `docs:`, `doc` |
| 安全修复 | 🔒 | `security`, `vulnerability` | `security:`, `安全` |

## Release Notes 模板

### 标准模板

```markdown
# 🎉 Release {VERSION}

## 📊 变更统计
- **新功能**: {FEATURE_COUNT} 个
- **Bug 修复**: {BUG_FIX_COUNT} 个
- **功能改进**: {ENHANCEMENT_COUNT} 个
- **破坏性变更**: {BREAKING_COUNT} 个

## ✨ 新功能
{FEATURES}

## 🐛 Bug 修复
{BUG_FIXES}

## 🔧 功能改进
{ENHANCEMENTS}

## ⚠️ 破坏性变更
{BREAKING_CHANGES}

## 🙏 贡献者
{CONTRIBUTORS}

---
**完整变更日志**: https://www.gitlink.org.cn/{OWNER}/{REPO}/compare/{PREV}...{VERSION}
```

> **条目格式要求**：每个变更条目必须在末尾标注作者，格式为 `- 变更描述 (#编号) (@作者)`。commit 无 PR 编号时格式为 `- 变更描述 (作者名)`。

### 简化模板

```markdown
# {VERSION}

## 新增
{FEATURES}

## 修复
{BUG_FIXES}

## 改进
{ENHANCEMENTS}
```

## 版本号规范

遵循语义化版本（Semantic Versioning）：`MAJOR.MINOR.PATCH`

| 变更类型 | 版本变化 | 示例 |
|----------|----------|------|
| 破坏性变更 | MAJOR +1 | `1.2.0` → `2.0.0` |
| 向后兼容的新功能 | MINOR +1 | `1.1.0` → `1.2.0` |
| 向后兼容的 Bug 修复 | PATCH +1 | `1.1.0` → `1.1.1` |

## API 注意事项

- `compare` API 无专用 shortcut，通过 `gitlink-cli api GET /:owner/:repo/compare/{head}...{base}` 调用
- `compare` API 另支持查询参数格式：`GET /v1/:owner/:repo/compare.json?from=&to=`
- `release +create` 的 `--body` 接受完整 Markdown，支持多行文本
- `release +view` / `release +delete` 必须使用 `version_id`（从 `release +list` 获取），不可用 `tag_name`
- 创建 Release 前务必让用户审核生成的 Notes 内容

## References

- [collect-data](references/collect-data.md) — 收集 commits、PR、Issue 数据
- [classify-rules](references/classify-rules.md) — 变更分类规则详解
- [generate-and-publish](references/generate-and-publish.md) — 生成 Notes 并发布
- [full-workflow](examples/full-workflow.md) — 完整端到端示例
- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证和全局参数
- [gitlink-release](../gitlink-release/SKILL.md) — Release 操作
