Back to Details

changelog-update

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changelog-Update Skill

Changelog-Update Skill

Update CHANGELOG.md with business-focused entries by systematically reviewing file changes.
通过系统化审查文件变更，为CHANGELOG.md添加聚焦业务的条目。

Summary

概述

Goal: Update CHANGELOG.md [Unreleased] section with business-focused entries via systematic file review.
StepActionKey Notes
1Gather changes
git diff
or 
git log
to identify changed files
2Create temp notes
.ai/workspace/changelog-notes-*.md
for categorized review
3Systematic file reviewRead each diff, identify business impact, categorize
4Holistic reviewRe-read notes -- what can users now do?
5Generate entryKeep a Changelog format under [Unreleased]
6Update CHANGELOG.mdInsert new entry under [Unreleased] section
7CleanupDelete temp notes file
Key Principles:
  • Business-focused language, not technical jargon (what users can do, not what classes were added)
  • For automated release notes from conventional commits, use 
    release-notes
    skill instead
  • Always delete temp notes file after completion
Note: For automated release notes from conventional commits, use the 
release-notes
skill instead.
目标：通过系统化文件审查，为CHANGELOG.md的[Unreleased]部分添加聚焦业务的条目。
步骤操作关键说明
1收集变更使用
git diff
或
git log
识别已变更文件
2创建临时笔记生成
.ai/workspace/changelog-notes-*.md
文件用于分类审查
3系统化文件审查阅读每个差异内容，识别业务影响并分类
4整体审查重新阅读笔记——用户现在可以做什么？
5生成条目按照Keep a Changelog格式在[Unreleased]下撰写
6更新CHANGELOG.md将新条目插入到[Unreleased]部分下
7清理删除临时笔记文件
核心原则：
  • 使用聚焦业务的语言，而非技术术语（描述用户能做什么，而非添加了哪些类）
  • 若要从约定式提交自动生成发布说明，请使用
    release-notes
    skill
  • 完成后务必删除临时笔记文件
注意：若要从约定式提交自动生成发布说明，请改用
release-notes
skill。

When to Use

使用场景

  • During development: Document feature/fix for users before PR/merge
  • PR preparation: Add business-focused entry to CHANGELOG.md
  • Manual documentation: When commits don't capture full business impact
Don't use for releases: Use 
release-notes
skill to generate versioned release docs.
  • 开发过程中：在PR/合并前为用户记录功能/修复内容
  • PR准备阶段：为CHANGELOG.md添加聚焦业务的条目
  • 手动文档编写：当提交信息无法完整体现业务影响时
版本发布时请勿使用：请使用
release-notes
skill生成带版本号的发布文档。

Pre-Execution Checklist

执行前检查清单

  1. Find existing CHANGELOG.md location
    • Check root: 
      ./CHANGELOG.md
      (preferred)
    • Fallback: 
      ./docs/CHANGELOG.md
    • If not found: Create at root
  2. Read current changelog to understand format and last entries
  1. 找到现有CHANGELOG.md的位置
    • 检查根目录：
      ./CHANGELOG.md
      （优先选择）
    • 备选：
      ./docs/CHANGELOG.md
    • 若未找到：在根目录创建
  2. 阅读当前变更日志，了解格式和最新条目

Workflow

工作流程

Step 1: Gather Changes

步骤1：收集变更

Determine change scope:
  • PR-based: 
    git diff origin/main...HEAD --name-only
  • Branch-based: 
    git log origin/main..HEAD --oneline
  • Commit-based: 
    git show {commit} --name-only
确定变更范围：
  • 基于PR：
    git diff origin/main...HEAD --name-only
  • 基于分支：
    git log origin/main..HEAD --oneline
  • 基于提交：
    git show {commit} --name-only

Step 2: Create Temp Notes File

步骤2：创建临时笔记文件

Create 
.ai/workspace/changelog-notes-{YYMMDD-HHMM}.md
:
markdown
undefined
创建
.ai/workspace/changelog-notes-{YYMMDD-HHMM}.md
：
markdown
undefined

Changelog Review Notes - {date}

Changelog Review Notes - {date}

Files Changed

Files Changed

  • file1.ts -
  • file2.cs -
  • file1.ts -
  • file2.cs -

Categories

Categories

Added (new features)

Added (new features)

Changed (modifications to existing)

Changed (modifications to existing)

Fixed (bug fixes)

Fixed (bug fixes)

Deprecated

Deprecated

Removed

Removed

Security

Security

Business Summary

Business Summary

<!-- What does this mean for users? --> 
undefined
<!-- What does this mean for users? --> 
undefined

Step 3: Systematic File Review

步骤3：系统化文件审查

For each changed file:
  1. Read file or diff
  2. Identify business impact (not just technical change)
  3. Check box and note in temp file
  4. Categorize into appropriate section
Business Focus Guidelines:
  • ❌ "Added 
    StageCategory
    enum"
  • ✅ "Added stage categories (Sourced, Applied, Interviewing, etc.) for pipeline tracking"
  • ❌ "Created 
    PipelineController.cs
    "
  • ✅ "Added API endpoints for pipeline management"
针对每个已变更文件：
  1. 阅读文件或差异内容
  2. 识别业务影响（而非仅技术变更）
  3. 勾选复选框并在临时文件中记录
  4. 归类到对应章节
聚焦业务的准则：
  • ❌ "Added 
    StageCategory
    enum"（错误示例）
  • ✅ "为Pipeline跟踪添加了阶段分类（已获取、已申请、面试中等）"（正确示例）
  • ❌ "Created 
    PipelineController.cs
    "（错误示例）
  • ✅ "为Pipeline管理添加了API端点"（正确示例）

Step 4: Holistic Review

步骤4：整体审查

Read temp notes file completely. Ask:
  • What's the main feature/fix?
  • Who benefits and how?
  • What can users now do that they couldn't before?
完整阅读临时笔记文件，思考：
  • 主要功能/修复是什么？
  • 谁会受益，如何受益？
  • 用户现在可以做哪些之前无法做到的事情？

Step 5: Generate Changelog Entry

步骤5：生成变更日志条目

Format (Keep a Changelog):
markdown
undefined
格式遵循Keep a Changelog：
markdown
undefined

[Unreleased]

[Unreleased]

{Feature/Module Name}: {Feature Title}

{Feature/Module Name}: {Feature Title}

Feature/Fix: {One-line business description}
Feature/Fix: {单行业务描述}

Added

Added

  • {Business-focused item}
  • {聚焦业务的条目}

Changed

Changed

  • {What behavior changed}
  • {哪些行为发生了变更}

Fixed

Fixed

  • {What issue was resolved}
undefined
  • {解决了什么问题}
undefined

Step 6: Update Changelog

步骤6：更新变更日志

  1. Read existing CHANGELOG.md
  2. Insert new entry under [Unreleased] section
  3. If no [Unreleased] section, create it after the header
  1. 阅读现有CHANGELOG.md
  2. 将新条目插入到[Unreleased]部分下
  3. 若没有[Unreleased]部分，在标题后创建该部分

Step 7: Cleanup

步骤7：清理

Delete temp notes file: 
.ai/workspace/changelog-notes-*.md
删除临时笔记文件：
.ai/workspace/changelog-notes-*.md

Examples

示例

Good Entry

良好条目

markdown
undefined
markdown
undefined

TextSnippet: Content Management

TextSnippet: Content Management

Feature: Rich text snippet management with categorization and search capabilities.
Feature: Rich text snippet management with categorization and search capabilities.

Added

Added

  • Rich text editor with markdown support
  • Category-based organization with tags
  • Full-text search across snippets
  • Multi-language content support (EN/VI)
undefined
  • Rich text editor with markdown support
  • Category-based organization with tags
  • Full-text search across snippets
  • Multi-language content support (EN/VI)
undefined

Bad Entry (Too Technical)

不良条目（过于技术化）

markdown
undefined
markdown
undefined

Pipeline Changes

Pipeline Changes

Added

Added

  • Pipeline.cs entity
  • StageCategory enum
  • PipelineController
  • SavePipelineCommand
undefined
  • Pipeline.cs entity
  • StageCategory enum
  • PipelineController
  • SavePipelineCommand
undefined

Anti-Patterns

反模式

  1. ❌ Creating new changelog in docs/ when root exists
  2. ❌ Skipping file review (leads to missed changes)
  3. ❌ Technical jargon without business context
  4. ❌ Forgetting to delete temp notes file
  5. ❌ Not using [Unreleased] section
  1. ❌ 根目录已存在CHANGELOG.md时，仍在docs/下创建新的变更日志
  2. ❌ 跳过文件审查（会导致遗漏变更）
  3. ❌ 使用无业务上下文的技术术语
  4. ❌ 忘记删除临时笔记文件
  5. ❌ 不使用[Unreleased]部分

IMPORTANT Task Planning Notes

重要任务规划说明

  • Always plan and break many small todo tasks
  • Always add a final review todo task to review the works done at the end to find any fix or enhancement needed
  • 始终将任务拆分为多个小的待办事项
  • 始终添加一个最终审查的待办任务，检查已完成的工作是否需要修复或优化