# 生成并发布 Release Notes

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **CRITICAL — 此为写入操作，执行前务必确认用户已审核 Release Notes 内容。**

将分类整理后的变更数据套用模板，生成 Markdown 格式的 Release Notes，并发布到 GitLink。

## 模板

### 标准模板

```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}
```

### 简化模板（适用于 patch 版本或小型发布）

```markdown
# {VERSION}

## 新增
{FEATURES}

## 修复
{BUG_FIXES}

## 改进
{ENHANCEMENTS}

## 贡献者
{CONTRIBUTORS}

[完整变更](https://www.gitlink.org.cn/{OWNER}/{REPO}/compare/{PREV}...{VERSION})
```

## 模板占位符说明

| 占位符 | 来源 |
|--------|------|
| `{VERSION}` | 用户指定或 AI 推断的新版本号（如 `v1.2.0`） |
| `{PREV}` | `release +list` 获取的上一个版本 tag |
| `{OWNER}` | 仓库所有者，从 git remote 解析 |
| `{REPO}` | 仓库名称，从 git remote 解析 |
| `{FEATURE_COUNT}` 等 | 分类后的各类变更数量 |
| `{FEATURES}` 等 | 分类后的各类变更条目，每条一行 `- 描述 (#编号) (@作者)` |
| `{CONTRIBUTORS}` | 从 commits/PRs 去重后的贡献者列表 |

## 命令

### 新建 Release

```bash
gitlink-cli release +create \
  --tag v1.2.0 \
  --name "v1.2.0" \
  --body "<Markdown 格式的 Release Notes>"
```

| 参数 | 必填 | 说明 |
|------|------|------|
| `--tag` | **是** | 版本 tag（如 `v1.2.0`） |
| `--name` | **是** | Release 名称，通常与 tag 一致 |
| `--body` | 否 | Release Notes 正文（Markdown，支持多行） |
| `--target` | 否 | 目标分支，默认 `master` |
| `--prerelease` | 否 | 标记为预发布版本 |

### 更新已有 Release

```bash
gitlink-cli release +update \
  --id <version_id> \
  --body "<更新后的 Release Notes>"
```

> ⚠️ `release +update` 使用 `version_id`（数字 ID，从 `release +list` 获取），不是 `tag_name`。

## Workflow

> [!CAUTION]
> Release Notes 发布是 **Write Operation**，执行前必须让用户审核内容。

1. **生成** Release Notes 草稿（套用模板填充数据）
2. **展示**草稿给用户审核
3. **确认**用户同意后才执行 `release +create` 或 `release +update`
4. **报告**创建的 Release URL 给用户

## 发布前检查清单

- [ ] 版本号遵循语义化版本规范
- [ ] 变更统计与实际一致
- [ ] 破坏性变更已明确标注
- [ ] 贡献者列表完整
- [ ] 无敏感信息泄露
- [ ] 对比链接可访问

## 注意事项

- `release +create --body` 接受完整 Markdown，换行和格式由模板控制
- `release +view` / `release +delete` 使用 `version_id`（数字），不是 `tag_name`
- 可用 `release +update --body` 修正已发布的 Notes
- 首个版本（无上一版本）省略对比链接

## References

- [collect-data](collect-data.md) — 收集变更数据
- [classify-rules](classify-rules.md) — 变更分类规则
- [full-workflow](../examples/full-workflow.md) — 完整端到端示例
- [gitlink-release](../../gitlink-release/SKILL.md) — Release 操作
- [release +create](../../gitlink-release/references/gitlink-release-create.md) — 创建 Release 详细参数
