Back to Details

forge-update-changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update Changelog

更新变更日志

Update CHANGELOG.md with user-facing changes from recent development work.
更新CHANGELOG.md，记录近期开发工作中面向用户的变更。

Input

输入参数

Optional: A date (YYYY-MM-DD) or commit hash to start from: $ARGUMENTS
If not provided, will look at commits since the last changelog update.
可选：起始日期（格式为YYYY-MM-DD）或提交哈希值：$ARGUMENTS
如果未提供该参数，将查看自上次变更日志更新以来的提交记录。

Process

操作流程

Step 1: Read Current Changelog

步骤1：读取当前变更日志

bash
undefined
bash
undefined

Read the current changelog to understand the format and last update

Read the current changelog to understand the format and last update

cat CHANGELOG.md
undefined
cat CHANGELOG.md
undefined

Step 2: Gather Recent Changes

步骤2：收集近期变更

bash
undefined
bash
undefined

Get recent commits (adjust date/commit as needed)

Get recent commits (adjust date/commit as needed)

Default: commits from the last month

Default: commits from the last month

git log --oneline --since="1 month ago"
git log --oneline --since="1 month ago"

For more detail on specific commits

For more detail on specific commits

git log --format="%h %s" --since="1 month ago"
git log --format="%h %s" --since="1 month ago"

Or since a specific commit

Or since a specific commit

git log --oneline <commit>..HEAD
undefined
git log --oneline <commit>..HEAD
undefined

Step 3: Filter for User-Facing Changes

步骤3：筛选面向用户的变更

Review commits and identify only those that affect end users:
Include:
  • feat:
    - New features users can see or use
  • fix:
    - Bug fixes that affected user experience
  • perf:
    - Performance improvements users would notice
Exclude (internal changes):
  • refactor:
    - Code restructuring (unless it changes behavior)
  • test:
    - Test additions/changes
  • chore:
    - Maintenance tasks
  • ci:
    - CI/CD changes
  • docs:
    - Documentation changes (unless user-facing help docs)
  • Internal API changes
  • Development tooling updates
审核提交记录，仅识别那些会影响终端用户的变更：
需包含：
  • feat:
    - 用户可见或可使用的新功能
  • fix:
    - 影响用户体验的Bug修复
  • perf:
    - 用户可感知的性能优化
需排除（内部变更）：
  • refactor:
    - 代码重构（除非改变了功能行为）
  • test:
    - 测试用例的添加或修改
  • chore:
    - 维护任务
  • ci:
    - CI/CD相关变更
  • docs:
    - 文档变更（除非是面向用户的帮助文档）
  • 内部API变更
  • 开发工具更新

Step 4: Group Changes by Category

步骤4：按类别分组变更

Organize changes into user-friendly categories that match the project. Common categories include:
  • New Features - Major new functionality
  • Improvements - Enhancements to existing features
  • Bug Fixes - Issues that affected users
  • Performance - Speed and responsiveness improvements
  • Security - Security-related improvements
Adapt categories to the project's domain (e.g., a SaaS app might use "Dashboard", "Billing", "Integrations").
将变更整理为符合项目需求的用户友好型类别。常见类别包括：
  • 新功能 - 主要的新功能
  • 功能改进 - 现有功能的增强
  • Bug修复 - 影响用户的问题修复
  • 性能优化 - 速度和响应性提升
  • 安全增强 - 安全相关的改进
可根据项目领域调整类别（例如，SaaS应用可使用“仪表盘”、“计费”、“集成”等类别）。

Step 5: Write User-Friendly Descriptions

步骤5：撰写用户友好的描述

Transform technical commit messages into plain language:
Technical → User-Friendly Examples:
  • feat(auth): add OAuth2 login with Google
    → "Sign in with your Google account"
  • fix: file upload fails for large images
    → "Fixed uploading large images"
  • perf(frontend): optimize bundle size with code splitting
    → "Faster app loading times"
  • feat(dashboard): add export to CSV
    → "Export your data as a spreadsheet"
Writing Guidelines:
  • Use active voice ("Create", "See", "Download")
  • Focus on benefits, not implementation
  • Avoid technical jargon (no "API", "endpoints", "cache", "SSR")
  • Keep entries short (one line preferred)
  • Use bold for feature names: Feature name - description
将技术化的提交信息转换为通俗易懂的语言：
技术描述 → 用户友好描述示例：
  • feat(auth): add OAuth2 login with Google
    → “使用Google账号登录”
  • fix: file upload fails for large images
    → “修复了大图片上传失败的问题”
  • perf(frontend): optimize bundle size with code splitting
    → “应用加载速度提升”
  • feat(dashboard): add export to CSV
    → “将数据导出为CSV文件”
撰写指南：
  • 使用主动语态（如“创建”、“查看”、“下载”）
  • 聚焦于用户收益，而非实现细节
  • 避免技术术语（如“API”、“端点”、“缓存”、“SSR”等）
  • 保持条目简洁（优先使用单行描述）
  • 功能名称使用加粗格式：功能名称 - 描述

Step 6: Update CHANGELOG.md

步骤6：更新CHANGELOG.md

Add a new section at the top (after the header), following this format:
markdown
undefined
在文档顶部（标题下方）添加新的章节，遵循以下格式：
markdown
undefined

Month Year

Month Year

Category Name

Category Name

  • Feature name - Brief, user-friendly description
  • Another feature - What users can now do
  • Feature name - Brief, user-friendly description
  • Another feature - What users can now do

Another Category

Another Category

  • Fix description - What was fixed and how it helps

**Formatting Rules:**
- Use `## Month Year` for date headers
- Use `### Category` for grouping related changes
- Use `---` between months for visual separation
- Bold the feature/fix name, then describe it
- Keep the most recent changes at the top
  • Fix description - What was fixed and how it helps

**格式规则：**
- 使用`## 月份 年份`作为日期标题
- 使用`### 类别`对相关变更进行分组
- 月份之间使用`---`进行视觉分隔
- 功能/修复名称加粗，然后添加描述
- 最新的变更放在最顶部

Step 7: Review and Verify

步骤7：审核与验证

Before committing, verify:
  • Only user-facing changes are included
  • No technical jargon
  • Consistent formatting with existing entries
  • Changes are in the correct time period
  • No duplicate entries
提交前，请验证以下内容：
  • 仅包含面向用户的变更
  • 无技术术语
  • 格式与现有条目保持一致
  • 变更属于正确的时间段
  • 无重复条目

Example Transformation

转换示例

Git log:
fb6c12f feat(auth): add OAuth2 login with Google (#42)
443f225 feat(dashboard): add CSV export for reports (#41)
0efa767 fix(api): handle rate limiting gracefully (#39)
d9a51f2 perf(frontend): lazy load dashboard charts (#38)
52105d7 fix(notifications): emails not sent for new signups (#37)
Changelog entry:
markdown
undefined
Git日志：
fb6c12f feat(auth): add OAuth2 login with Google (#42)
443f225 feat(dashboard): add CSV export for reports (#41)
0efa767 fix(api): handle rate limiting gracefully (#39)
d9a51f2 perf(frontend): lazy load dashboard charts (#38)
52105d7 fix(notifications): emails not sent for new signups (#37)
变更日志条目：
markdown
undefined

January 2025

January 2025

New Features

New Features

  • Google sign-in - Sign in with your Google account for faster access
  • Export reports - Download your reports as CSV spreadsheets
  • Google sign-in - Sign in with your Google account for faster access
  • Export reports - Download your reports as CSV spreadsheets

Bug Fixes

Bug Fixes

  • Notification emails - New users now correctly receive welcome emails
  • Notification emails - New users now correctly receive welcome emails

Performance

Performance

  • Faster dashboard - Charts load more quickly on the dashboard
undefined
  • Faster dashboard - Charts load more quickly on the dashboard
undefined

Important Guidelines

重要指南

  1. User perspective: Always ask "Would a user notice or care about this?"
  2. No attribution: Don't include author names or PR numbers
  3. No time estimates: Don't say "now X% faster" unless you have real metrics
  4. Positive framing: "Fixed X" is better than "X was broken"
  5. Combine related changes: Multiple commits for one feature = one changelog entry
  6. Skip internal changes: Refactors, test updates, CI changes are not user-facing
  1. 用户视角：始终问自己“用户会注意到或关心这个变更吗？”
  2. 不添加署名：不要包含作者姓名或PR编号
  3. 不添加时间估算：除非有真实数据，否则不要说“现在速度提升X%”
  4. 正面表述：“修复了X问题”比“X曾出现故障”更好
  5. 合并相关变更：同一功能的多个提交合并为一个变更日志条目
  6. 跳过内部变更：重构、测试更新、CI变更不属于面向用户的内容

Related Skills

相关技能

Full workflow: 
forge-setup-project
→ 
forge-create-issue
→ 
forge-implement-issue
→ 
forge-reflect-pr
→ 
forge-address-pr-feedback
→ 
forge-update-changelog
完整工作流： 
forge-setup-project
→ 
forge-create-issue
→ 
forge-implement-issue
→ 
forge-reflect-pr
→ 
forge-address-pr-feedback
→ 
forge-update-changelog

Example Usage

使用示例

/forge-update-changelog
/forge-update-changelog 2025-01-01
/forge-update-changelog abc123
/forge-update-changelog
/forge-update-changelog 2025-01-01
/forge-update-changelog abc123