Changelog Management

自动化脚本（推荐）

使用辅助脚本，根据上一个标签以来的提交，按变更日志类别分组并生成草稿部分。

脚本路径：

.ai/skills/update-changelog/scripts/update-changelog.ps1

仅预览（打印生成的 Markdown）：

powershell -NoProfile -ExecutionPolicy Bypass -File .ai/skills/update-changelog/scripts/update-changelog.ps1

根据明确指定的标签/版本生成草稿并保存到文件：

powershell -NoProfile -ExecutionPolicy Bypass -File .ai/skills/update-changelog/scripts/update-changelog.ps1 -FromTag v0.18.9 -Version 0.19.0 -OutputPath build/changelog-draft.md

直接应用到 docs/CHANGELOG.md：

powershell -NoProfile -ExecutionPolicy Bypass -File .ai/skills/update-changelog/scripts/update-changelog.ps1 -FromTag v0.18.9 -Version 0.19.0 -Apply

注意：

• -Version 默认使用根目录中的 Directory.Build.props。
• -FromTag 默认使用 git describe --tags --abbrev=0。
• 脚本会更新 ## vX.Y.Z（替换该版本的现有部分，或插入到 ## Unreleased 之后）。
• 仍需人工审核合并质量和贡献者署名规则。

版本分组策略

基于 Git 标签进行合并

• 重要：检查 git tag -l，以确定上一个已发布的版本标签。
• 上一个 Git 标签之后的所有提交都必须合并到下一个次要版本的单个标题下。
  • 示例：如果上一个标签是 v0.15.5，那么该标签之后的所有提交（包括任何变更日志部分，如 v0.15.6、v0.15.7、v0.16.0、v0.16.1）都必须合并到 v0.16.0。
• 切勿在 Git 标签之间创建多个版本标题。任意两个标签之间只能有一个版本标题。

次要版本拆分

• 始终按次要版本拆分变更（例如，v0.8.0、v0.9.0、v0.10.0），即使 Directory.Build.props 或 Git 标签中没有明确标示。
• 分析 git log 和 Directory.Build.props 历史，以确定版本提升已发生或隐含的边界。

合并规则

• 补丁版本：将补丁版本（例如，v0.8.x）合并到下一个重要的次要版本（例如，v0.9.0），除非该补丁版本是重要的独立发布版本。
  • 示例：v0.8.1、v0.8.2、v0.8.3 中的条目应合并并列在 v0.9.0 下。
  • 如有需要，保留原始上下文（例如，“功能：... (v0.8.1)”）。
• 预发布版本修复：将先前版本发布后的修复移至下一个次要版本。
  • 示例：在 v0.7.7 标签之后完成、但历史上列在 v0.7.7 标题下的修复，应移至 v0.8.0。

提交处理

指定提交归属

• 遵循用户将特定提交指定到特定版本的要求。
• 示例：“将提交 298457a 列在 v0.11.0 下。”
• 指定前务必核实提交哈希和主题。

署名

• 外部贡献者：为外部贡献者的拉取请求署名时，包含 PR 编号和其用户名。
  • 格式：(#PR_NUMBER, @username)
  • 示例：(#77, @Hexeption)
• 维护者合并：除非维护者（例如 McoreD）的合并提交包含其他提交未涵盖的重要独特工作，否则不要对其进行明确署名。重点是感谢其他用户。

分类

在每个版本中使用标准类别对变更分组：

• 功能：新功能。
• 修复：错误修复。
• 重构：不会改变外部行为的代码改进。
• 构建：构建系统、依赖项和打包。
• 核心：核心基础变更。
• 基础设施：代码库、Git 或工作流变更。

合并条目以减少行数

重要：将相关提交合并为单个条目，使变更日志简洁易读。

指南：

• 按组件和用途分组：合并影响同一组件且用途相同的多个提交。
• 保留所有提交哈希：合并时，在同一行中包含所有相关提交哈希。
• 目标缩减幅度：通过合并相关工作，力求减少 30-50% 的行数。

示例：

合并前（冗长）：

- **Media Explorer**: Add `IUploaderExplorer` interface `(9deedf9)`
- **Media Explorer**: Implement S3 file browser `(9deedf9)`
- **Media Explorer**: Implement Imgur album browser `(9deedf9)`
- **Media Explorer**: Add navigation, breadcrumbs, search, filter `(9deedf9)`
- **Media Explorer**: Add bandwidth savings banner `(e374160)`

合并后（已合并）：

- **Media Explorer**: Implement provider file browsing with S3 and Imgur support, including navigation, search, filtering, and CDN thumbnail optimization `(9deedf9, e374160)`

合并前（移动端功能）：

- **Mobile**: Add adaptive mobile theming infrastructure `(4b79ddb)`
- **Mobile**: Refactor mobile views for adaptive native styling `(a7cfb22)`
- **Mobile**: Align mobile heads with native theming defaults `(1e5f9eb)`
- **Mobile**: Complete sprint 5 mobile theming polish and docs `(30bbe98)`
- **Mobile**: Add mobile upload queue and picker `(68d97d9)`
- **Mobile**: Add mobile upload history screens `(52d6ad2)`

合并后（已合并）：

- **Mobile**: Add adaptive theming infrastructure with native styling polish `(4b79ddb, a7cfb22, 1e5f9eb, 30bbe98)`
- **Mobile**: Add upload queue, picker, and history screens `(68d97d9, 52d6ad2)`

合并前（修复）：

- **Scrolling Capture**: Always auto-scroll to top `(1fa45f2)`
- **Scrolling Capture**: Apply workflow settings and refresh hotkeys `(971219c)`
- **Scrolling Capture**: Use current scroll position for detection `(8ac2c8b)`

合并后（已合并）：

- **Scrolling Capture**: Improve auto-scroll behavior and workflow settings integration `(1fa45f2, 971219c, 8ac2c8b)`

不应合并的情况：

• 来自不同组件的提交（例如，不要将“Mobile”与“Linux Capture”合并）
• 带有外部贡献者署名的提交（为方便查看，请保持独立）
• 值得单独列出的重要独立功能

格式

遵循 Keep a Changelog 格式，并使用语义化版本控制。

## vX.Y.Z

### Features
- **Component**: Description `(short-hash)`
- **Component**: Description `(short-hash, short-hash)`

### Fixes
- Description `(short-hash)`

工作流

分步流程

1. 确定最近的 Git 标签

   git tag -l | Sort-Object -Descending | Select-Object -First 1
   

   这将确定版本合并的边界。

2. 获取最近标签之后的提交

   git log v0.X.Y..HEAD --oneline --no-decorate
   

   分析所有需要记录的提交。

3. 检查 Directory.Build.props 中的当前版本 读取 <Version> 属性以确定目标版本号。

4. 合并版本标题

   • 移除最近的 Git 标签与当前 HEAD 之间的所有版本标题
   • 为下一个次要版本（取自 Directory.Build.props）创建一个标题
   • 将所有提交移入这个版本标题下

5. 对提交分类

   • 将提交分为：功能、修复、重构、构建、文档
   • 在每个类别中，按组件分组（例如，Mobile、Linux Capture、Editor）

6. 合并相关条目

   • 找出影响同一组件且用途相似的提交
   • 将其合并为简洁完整的条目
   • 保留所有提交哈希
   • 力求将行数减少 30–50%

7. 格式化并验证

   • 确保 Markdown 格式正确
   • 确认所有提交哈希均已包含
   • 检查是否保留了外部贡献者署名
   • 确认符合 Keep a Changelog 格式

命令序列示例

# Get last tag
$lastTag = git tag -l | Sort-Object -Descending | Select-Object -First 1

# Get commits since tag
git log $lastTag..HEAD --oneline --no-decorate

# Check current version
$version = Select-String -Path "Directory.Build.props" -Pattern '<Version>(.*)</Version>' | ForEach-Object { $_.Matches.Groups[1].Value }

# Update CHANGELOG.md with consolidated entries