Back to Details

changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Phase 1: Parse Arguments

第一阶段：解析参数

Read the argument for the target version or sprint number. If a version is given, use the corresponding git tag. If a sprint number is given, use the sprint date range.
Verify the repository is initialized: run 
git rev-parse --is-inside-work-tree
to confirm git is available. If not a git repo, inform the user and abort gracefully.
读取目标版本或迭代编号的参数。如果指定了版本，则使用对应的Git标签；如果指定了迭代编号，则使用该迭代的日期范围。
验证仓库已初始化：运行
git rev-parse --is-inside-work-tree
确认Git可用。如果不是Git仓库，告知用户并优雅终止流程。

Phase 2: Gather Change Data

第二阶段：收集变更数据

Read the git log since the last tag or release:
git log --oneline [last-tag]..HEAD
If no tags exist, read the full log or a reasonable recent range (last 100 commits).
Read sprint reports from 
production/sprints/
for the relevant period to understand planned work and context behind changes.
Read completed design documents from 
design/gdd/
for any new features implemented during this period.
读取从上一个标签或版本发布以来的Git日志：
git log --oneline [last-tag]..HEAD
如果没有标签存在，则读取完整日志或最近的合理范围（最近100次提交）。
从
production/sprints/
读取相关时间段的迭代报告，了解计划工作和变更背后的背景信息。
从
design/gdd/
读取该时间段内已完成的设计文档，查看所有已实现的新功能。

Phase 3: Categorize Changes

第三阶段：分类变更

Categorize every change into one of these categories:
  • New Features: Entirely new gameplay systems, modes, or content
  • Improvements: Enhancements to existing features, UX improvements, performance gains
  • Bug Fixes: Corrections to broken behavior
  • Balance Changes: Tuning of gameplay values, difficulty, economy
  • Known Issues: Issues the team is aware of but have not yet resolved
  • Miscellaneous: Changes that do not fit the above categories, or commits whose messages are too vague to classify confidently
For each commit, check whether the message contains a task ID or story reference (e.g. 
[STORY-123]
, 
TR-
, 
#NNN
, or similar). Count commits that lack any task reference and include this count in the Phase 4 Metrics section as: 
Commits without task reference: [N]
.
将每一项变更归类到以下类别之一：
  • 新功能：全新的游戏玩法系统、模式或内容
  • 优化改进：对现有功能的增强、用户体验优化、性能提升
  • Bug修复：修复异常行为
  • 平衡性调整：调整游戏数值、难度、经济系统
  • 已知问题：团队已发现但尚未解决的问题
  • 其他杂项：不符合上述类别的变更，或提交信息过于模糊无法准确分类的内容
对于每一次提交，检查提交信息是否包含任务ID或需求引用（例如
[STORY-123]
、
TR-
、
#NNN
或类似格式）。统计缺少任何任务引用的提交数量，并在第四阶段的指标部分中显示：
无任务引用的提交数：[N]
。

Phase 4: Generate Internal Changelog

第四阶段：生成内部更新日志

markdown
undefined
markdown
undefined

Internal Changelog: [Version]

内部更新日志：[版本号]

Date: [Date] Sprint(s): [Sprint numbers covered] Commits: [Count] ([first-hash]..[last-hash])
日期：[日期] 涉及迭代：[涵盖的迭代编号] 提交记录：[数量]（[起始哈希值]..[结束哈希值]）

New Features

新功能

  • [Feature Name] -- [Technical description, affected systems]
    • Commits: [hash1], [hash2]
    • Owner: [who implemented it]
    • Design doc: [link if applicable]
  • [功能名称] -- [技术描述、涉及系统]
    • 提交记录：[哈希值1], [哈希值2]
    • 负责人：[实现者]
    • 设计文档：[链接（如有）]

Improvements

优化改进

  • [Improvement] -- [What changed technically and why]
    • Commits: [hashes]
    • Owner: [who]
  • [改进内容] -- [技术层面的变更及原因]
    • 提交记录：[哈希值列表]
    • 负责人：[相关人员]

Bug Fixes

Bug修复

  • [BUG-ID] [Description of bug and root cause]
    • Fix: [What was changed]
    • Commits: [hashes]
    • Owner: [who]
  • [BUG-ID] [Bug描述及根本原因]
    • 修复内容：[变更内容]
    • 提交记录：[哈希值列表]
    • 负责人：[相关人员]

Balance Changes

平衡性调整

  • [What was tuned] -- [Old value -> New value] -- [Design intent]
    • Owner: [who]
  • [调整内容] -- [旧值 -> 新值] -- [设计意图]
    • 负责人：[相关人员]

Technical Debt / Refactoring

技术债务/重构

  • [What was cleaned up and why]
    • Commits: [hashes]
  • [清理内容及原因]
    • 提交记录：[哈希值列表]

Miscellaneous

其他杂项

  • [Change that didn't fit other categories, or vague commit message]
    • Commits: [hashes]
  • [不符合其他类别的变更，或模糊的提交信息]
    • 提交记录：[哈希值列表]

Known Issues

已知问题

  • [Issue description] -- [Severity] -- [ETA for fix if known]
  • [问题描述] -- [严重程度] -- [预计修复时间（如有）]

Metrics

指标

  • Total commits: [N]
  • Files changed: [N]
  • Lines added: [N]
  • Lines removed: [N]
  • Commits without task reference: [N]

---
  • 总提交数：[N]
  • 修改文件数：[N]
  • 添加代码行数：[N]
  • 删除代码行数：[N]
  • 无任务引用的提交数：[N]

---

Phase 5: Generate Player-Facing Changelog

第五阶段：生成面向玩家的更新日志

markdown
undefined
markdown
undefined

What is New in [Version]

[版本号]更新内容

New Features

新功能

  • [Feature Name]: [Player-friendly description of what they can now do and why it is exciting. Focus on the experience, not the implementation.]
  • [功能名称]：[面向玩家的友好描述，说明玩家现在可以做什么以及该功能的有趣之处。聚焦体验而非实现细节。]

Improvements

优化改进

  • [What improved]: [How this makes the game better for the player. Be specific but avoid jargon.]
  • [改进内容]：[该改进如何提升玩家的游戏体验。具体描述但避免技术术语。]

Bug Fixes

Bug修复

  • Fixed an issue where [describe what the player experienced, not what was wrong in the code]
  • Fixed [player-visible symptom]
  • 修复了[玩家遇到的问题描述，而非代码层面的错误]
  • 修复了[玩家可见的症状]

Balance Changes

平衡性调整

  • [What changed in player-understandable terms and the design intent. Example: "Healing potions now restore 50 HP (up from 30) -- we felt players needed more recovery options in late-game encounters."]
  • [用玩家易懂的语言描述变更内容及设计意图。示例：“治疗药水现在恢复50点生命值（原为30点）——我们认为玩家在后期战斗中需要更多的恢复选项。”]

Known Issues

已知问题

  • We are aware of [issue description in player terms] and are working on a fix. [Workaround if one exists.]
Thank you for playing! Your feedback helps us make the game better. Report issues at [link].

---
  • 我们已注意到[用玩家视角描述的问题]，正在修复中。[如有解决方案请说明。]
感谢您的游玩！您的反馈有助于我们改进游戏。 请通过[链接]提交问题反馈。

---

Phase 6: Output

第六阶段：输出结果

Output both changelogs to the user. The internal changelog is the primary working document. The player-facing changelog is ready for community posting after review.
向用户输出两个版本的更新日志。内部更新日志是主要的工作文档，面向玩家的更新日志经审核后即可用于社区发布。

Phase 7: Offer File Write

第七阶段：提供写入文件选项

After presenting the changelogs, ask the user:
"May I write this changelog to 
docs/CHANGELOG.md
? [A] Yes, append this entry (recommended if the file already exists) [B] Yes, overwrite the file entirely [C] No — I'll copy it manually"
  • Check whether 
    docs/CHANGELOG.md
    exists before asking. If it does, default the recommendation to [A] append.
  • If the user selects [A]: append the new internal changelog entry to the top of the existing file (newest entries first).
  • If the user selects [B]: overwrite the file with the new changelog.
  • If the user selects [C]: stop here without writing.
After a successful write: Verdict: CHANGELOG WRITTEN — changelog saved to 
docs/CHANGELOG.md
. If the user declines: Verdict: COMPLETE — changelog generated.
展示更新日志后，询问用户：
“是否将此更新日志写入
docs/CHANGELOG.md
？ [A] 是，追加此条目（如果文件已存在，建议选择此项） [B] 是，完全覆盖文件 [C] 否 — 我将手动复制”
  • 在询问前检查
    docs/CHANGELOG.md
    是否存在。如果存在，默认推荐选择**[A] 追加**。
  • 如果用户选择[A]：将新的内部更新日志条目追加到现有文件顶部（最新条目优先）。
  • 如果用户选择[B]：用新的更新日志覆盖文件内容。
  • 如果用户选择[C]：在此终止流程，不执行写入操作。
写入成功后显示：结果：更新日志已写入 — 更新日志已保存至
docs/CHANGELOG.md
。 如果用户拒绝写入：结果：完成 — 更新日志已生成。

Phase 7: Next Steps

第八阶段：后续步骤

  • Use 
    /patch-notes [version]
    to generate a styled, saved version for public release.
  • Use 
    /release-checklist
    before publishing the changelog externally.
  • 使用
    /patch-notes [version]
    生成用于公开发布的格式化版本并保存。
  • 在对外发布更新日志前，使用
    /release-checklist
    进行检查。

Guidelines

指导原则

  • Never expose internal code references, file paths, or developer names in the player-facing changelog
  • Group related changes together rather than listing individual commits
  • If a commit message is unclear, check the associated files and sprint data for context
  • Balance changes should always include the design reasoning, not just the numbers
  • Known issues should be honest — players appreciate transparency
  • If the git history is messy (merge commits, reverts, fixup commits), clean up the narrative rather than listing every commit literally
  • 切勿在面向玩家的更新日志中暴露内部代码引用、文件路径或开发者姓名
  • 将相关变更分组展示，而非单独列出每一次提交
  • 如果提交信息不清晰，查看关联文件和迭代数据获取背景信息
  • 平衡性调整应始终包含设计思路，而非仅列出数值
  • 已知问题应如实告知——玩家重视透明度
  • 如果Git历史记录混乱（合并提交、回退提交、修正提交），梳理清晰的叙述逻辑，而非逐字列出每一次提交