build-game-changelog

构建游戏更新日志

将更新日志构建为一个发布系统，而不是装饰性的模态框。维护一份权威记录，将其与生产历史、游戏菜单导航和发布验证关联起来。

使用这种思维模型

• 记录是玩家实际收到内容的公开凭证。
• 版本标识一次成功的生产发布，而不是一次开发提交。
• 最新的记录条目决定游戏各处显示的版本。
• 打开更新日志是可逆的菜单状态转换。
• 所有关闭入口都通过同一个返回操作处理。
• 只有当线上游戏验证了预期版本和行为后，发布才算完成。

从事实出发

编辑前先检查：

1. 阅读仓库说明，并保留无关改动。
2. 找到游戏的菜单或暂停状态机、返回操作、输入绑定、焦点行为和响应式布局。
3. 找到所有显示的版本、软件包版本、构建版本、部署序列、发布清单和现有更新日志。
4. 在可行时，查询成功的生产部署及其源代码修订版本。
5. 比较部署修订版本，确定玩家实际收到了哪些内容。

优先依据仓库、部署和实时运行环境中的证据，不要依赖聊天摘要或对提交说明的猜测。不要编造缺失的发布日期、源代码修订版本、功能或版本映射。

定义一次发布

将一次成功的、玩家可见的生产部署视为一个更新日志版本。

• 不要因本地提交、草稿、测试、失败的构建或已保存但未发布的构件而提升版本。
• 将一起发布的多个提交合并为一个版本，并列出多条更新说明。
• 单独部署的热修复应有自己的版本。
• 描述玩家可见的结果，而不是实现工作或原始提交说明。
• 将内部源代码和部署标识符放在记录元数据中，而非面向玩家的文案中。

沿用现有版本方案。如果一个新的 1.0 之前的游戏尚无版本方案，默认使用 0.9.0，并在每次生产发布时递增修订号：0.9.1、0.9.2，依此类推。除非有明确的产品里程碑，否则不要跳到新的次版本或主版本。

构建或补全记录

重建历史时按从旧到新的顺序处理，然后按从新到旧的顺序存储条目，以供渲染。

1. 列出成功的生产发布。
2. 将每次发布与其日期、已部署的源代码修订版本和部署标识符关联起来。
3. 对比每个源代码修订版本与上一次生产修订版本之间的差异。
4. 总结该次发布中用户可见的变化。
5. 采用默认方案时，将首次生产基线设为 0.9.0。
6. 如果有意义的上线工作早于部署跟踪，则将其合并到基线中。
7. 验证记录的数量、排序、唯一性和版本连续性。

如果证据不完整，请在内部元数据中标记来源未知，或暂停并请求澄清。绝不要编造一段看似整齐的历史。

使用单一数据源

将更新日志内容保存在经过类型检查或架构验证的结构化数据中。每个条目都应包含：

• 版本
• 发布日期
• 简短的发布标题
• 一条或多条面向玩家的详情
• 可用时提供部署版本或发布标识符
• 可用时提供准确的源代码修订版本

从最新的记录条目推导当前显示的版本。不要另行维护一个手写的版本常量。

明确存储游戏版本与部署版本之间的映射。只有在项目对此有保证并经过测试时，才使用 patch = deploymentOrdinal - 1 之类的公式。

避免使用自指的源代码元数据。一次提交无法包含自身最终的哈希值。可以选择：

• 将最新内联条目的源代码修订版本保留为待定，并在下次发布时补全；
• 在构建时注入准确的修订版本；或
• 将不可变的发布来源信息存储在源代码提交之外。

实现架构、状态机或测试时，请参阅 references/reference-architecture.md。

与游戏导航集成

将更新日志设为明确的菜单路由或屏幕状态。仅当游戏现有的菜单架构使用叠加层时，才使用叠加层。

• 打开前记录上一个菜单屏幕。
• 将版本控件设为切换开关：关闭时打开更新日志；打开时返回上一个屏幕。
• 让页眉切换控件、可见的 X、底部的“返回”操作、手柄取消操作和 Escape 都通过同一个关闭或返回函数处理。
• 使用游戏权威的输入绑定层，而不是添加相互冲突的全局 Escape 监听器。
• 尊重优先级更高的输入使用方，例如对话框、拖动操作、重新绑定流程和文本字段。
• 如果菜单已有相应处理方式，则忽略重复输入和受阻的过渡状态。
• 如果更新日志可以在游戏进行时打开，则保留先前的暂停状态。

打开时，将焦点放在关闭控件或面板标题上。关闭时，在可行的情况下将焦点还给触发控件。切勿让键盘或手柄焦点停留在已卸载的面板内。

应用持久的 UI 机制

适配现有游戏 UI，不要引入新的视觉语言。

• 将更新日志控件放在稳定的菜单实用功能区，与音效、设置或账户控件等并列。
• 在控件中显示当前版本。
• 在面板页眉中保留可见的关闭 X，并为其提供无障碍名称。
• 让当前版本标记和关闭控件保持可见，同时让更新记录列表独立滚动。
• 按时间倒序呈现更新记录，并使用语义化标题、日期和项目符号列表。
• 如果游戏的其他面板使用底部“返回”操作，则保留该操作。
• 对基于 Web 的游戏，使用 aria-expanded、aria-controls、带标签的面板，以及动态的打开或关闭标签。
• 在小屏幕上保留版本信息和关闭操作；缩小触控目标前，先精简次要文本。
• 使用适合游戏现有控制系统的触控目标。

优先使用简洁、具体的说明，例如“在检查点恢复活力”，而不是“各种修复”。除非玩家需要了解，否则避免使用仅供开发者理解的术语。

安全发布

按以下顺序操作：

1. 核实最新的线上版本和生产源代码。
2. 根据成功发布的版本序列确定下一个版本。
3. 实现玩家可见的更改，并且只添加一条待发布的更新记录。
4. 运行数据、交互、无障碍、响应式和构建检查。
5. 只提交预期的源代码。
6. 构建准确的已提交版本。
7. 发布该准确版本。
8. 在确认部署成功后，再将该版本标记为已发布。
9. 核实线上游戏显示了预期版本、历史记录数量、最新条目、最早基线及所有关闭路径，且没有运行时错误。
10. 如果部署顺序与记录不符，则进行核对或停止操作。

除非该元数据更新本身会部署给玩家，否则不要仅为补充上一版本的来源信息而创建另一个更新日志版本。尽可能将记录维护工作与下一次实际发布合并。

验证约定

要求通过自动化检查验证：

• 版本唯一且连续
• 按时间倒序排列
• 存在最早基线
• 当前版本由第一条记录推导得出
• 日期有效、标题非空且详情非空
• 部署标识符唯一
• 源代码修订有效或明确标记为待定
• 按数据顺序完整呈现所有历史记录
• 切换开关的关闭和打开状态
• X、“返回”、手柄取消操作和 Escape 使用相同的返回路径
• 打开时焦点位置正确，关闭时焦点恢复合理
• 列表独立滚动，且小屏幕上的控件均可触达

如果任务包含发布，最后必须提供生产环境验证。测试线上构建，而不只是本地预览。

避免以下问题

• 不要为每次提交都创建一个版本。
• 不要显示尚未发布的版本。
• 不要让软件包元数据、UI 徽标和版本记录不一致。
• 如果玩家是从其他菜单进入的，关闭时不要跳转到硬编码的主界面。
• 不要注册重复的 Escape 处理程序，以免一次关闭两层界面。
• 不要把唯一的关闭控件藏在很长的滚动列表中。
• 不要在面向玩家的说明中暴露源代码哈希或部署 ID。
• 没有证据时，不要改写历史记录。