Back to Details

build-game-changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build Game Changelog

构建游戏更新日志

Build the changelog as a release system, not a decorative modal. Keep one authoritative ledger connected to production history, game-menu navigation, and release verification.
将更新日志构建为一套发布系统，而非装饰性弹窗。维护一份与生产历史、游戏菜单导航及发布验证关联的权威账本。

Use this mental model

采用以下思维模型

  • The ledger is the public record of what players received.
  • A version identifies a successful production release, not a development commit.
  • The newest ledger entry defines the version shown throughout the game.
  • Opening the changelog is a reversible menu-state transition.
  • Every close affordance resolves through the same back action.
  • A release is complete only after the live game proves the expected version and behavior.
  • 账本是玩家所获内容的公开记录。
  • 版本代表一次成功的生产发布，而非开发提交。
  • 最新的账本条目定义游戏内全局显示的版本。
  • 打开更新日志是可逆转的菜单状态切换。
  • 所有关闭操作都通过同一返回动作完成。
  • 只有当线上游戏验证了预期版本及行为后，发布才算完成。

Start from truth

从真实信息入手

Inspect before editing:
  1. Read repository instructions and preserve unrelated work.
  2. Find the game’s menu or pause state machine, back action, input bindings, focus behavior, and responsive layout.
  3. Find every displayed version, package version, build version, deployment sequence, release manifest, and existing changelog.
  4. Query successful production deployments and their source revisions when available.
  5. Compare deployment revisions to identify what players actually received.
Prefer repository, deployment, and live-runtime evidence over chat summaries or commit-message guesses. Do not invent missing release dates, source revisions, features, or version mappings.
编辑前先核查：
  1. 阅读仓库说明，保留无关工作内容。
  2. 找到游戏的菜单/暂停状态机、返回动作、输入绑定、焦点行为及响应式布局。
  3. 找到所有显示版本、包版本、构建版本、部署序列、发布清单及现有更新日志。
  4. 查询可用的成功生产部署记录及其源版本。
  5. 对比部署版本，确认玩家实际获取的内容。
优先参考仓库、部署及运行时的真实证据，而非聊天摘要或提交信息猜测。不得编造缺失的发布日期、源版本、功能或版本映射关系。

Define one release

定义单个版本

Treat one successful player-visible production deployment as one changelog version.
  • Do not bump for local commits, drafts, tests, failed builds, or saved-but-unpublished artifacts.
  • Combine multiple commits shipped together into one version with several release notes.
  • Give a separately deployed hotfix its own version.
  • Describe player-visible outcomes, not implementation chores or raw commit messages.
  • Keep internal source and deployment identifiers in ledger metadata, not player-facing copy.
Retain an established version scheme. For a new pre-1.0 game without one, default to 
0.9.0
and increment the patch once per production release: 
0.9.1
, 
0.9.2
, and so on. Do not jump to a new minor or major version without an explicit product milestone.
将一次成功的、玩家可见的生产部署视为一个更新日志版本。
  • 本地提交、草稿、测试、失败构建或已保存但未发布的产物，无需升级版本。
  • 将一同发布的多个提交合并为一个版本，包含多条发布说明。
  • 单独部署的热修复需拥有独立版本。
  • 描述玩家可见的结果，而非实现细节或原始提交信息。
  • 内部源标识和部署标识仅保留在账本元数据中，不展示给玩家。
沿用已有的版本方案。对于无版本方案的1.0前新游戏，默认从
0.9.0
开始，每次生产发布升级补丁号：
0.9.1
、
0.9.2
等。若无明确的产品里程碑，不得直接跳转到新的次要版本或主要版本。

Build or backfill the ledger

构建或补全账本

Work oldest-to-newest when reconstructing history, then store entries newest-first for rendering.
  1. Enumerate successful production releases.
  2. Associate each release with its date, deployed source revision, and deployment identifier.
  3. Diff each source revision against the previous production revision.
  4. Summarize the user-visible changes in that release.
  5. Use the first production baseline as 
    0.9.0
    when adopting the default scheme.
  6. Consolidate meaningful launch work into the baseline if it predates deployment tracking.
  7. Verify the ledger count, ordering, uniqueness, and version continuity.
If evidence is incomplete, mark provenance unknown in internal metadata or stop for clarification. Never fabricate a neat history.
重构历史时按从旧到新的顺序处理，存储时按从新到旧的顺序排列以便渲染。
  1. 列举所有成功的生产发布。
  2. 为每个发布关联日期、部署源版本及部署标识。
  3. 对比每个源版本与上一个生产版本的差异。
  4. 总结该版本中用户可见的变更。
  5. 采用默认方案时，将首个生产基线设为
    0.9.0
    。
  6. 若部署追踪早于有意义的启动工作，将启动工作合并到基线中。
  7. 验证账本的条目数量、排序、唯一性及版本连续性。
若证据不完整，在内部元数据中标记溯源未知，或暂停工作等待澄清。切勿编造虚假的完整历史。

Use one data source

使用单一数据源

Keep changelog content in typed or schema-validated structured data. Give each entry:
  • version
  • release date
  • short release title
  • one or more player-facing details
  • deployment version or release identifier when available
  • exact source revision when available
Derive the displayed current version from the newest ledger entry. Do not maintain a second hand-written version constant.
Store an explicit mapping between game versions and deployment versions. Only use a formula such as 
patch = deploymentOrdinal - 1
when the project guarantees it and tests it.
Avoid self-referential source metadata. A commit cannot contain its own final hash. Either:
  • keep the newest inline entry’s source revision pending and backfill it during the next release;
  • inject the exact revision at build time; or
  • store immutable release provenance outside the source commit.
See references/reference-architecture.md when implementing the schema, state machine, or tests.
将更新日志内容存储为类型化或 schema 验证的结构化数据。每个条目需包含：
  • version
  • 发布日期
  • 简短发布标题
  • 一条或多条面向玩家的细节说明
  • 可用时的部署版本或发布标识
  • 可用时的精确源版本
从最新的账本条目中提取当前显示版本。不得维护手写的版本常量。
存储游戏版本与部署版本的明确映射。仅当项目能保证并测试时，才使用
patch = deploymentOrdinal - 1
这类公式。
避免自引用的源元数据。提交无法包含自身的最终哈希值。可选择以下方式：
  • 保留最新内联条目的源版本为待填充状态，在下一次发布时补全；
  • 在构建时注入精确版本；或
  • 在源提交之外存储不可变的发布溯源信息。
实现 schema、状态机或测试时，可参考references/reference-architecture.md。

Integrate with game navigation

与游戏导航集成

Make the changelog an explicit menu route or screen state. Use an overlay only when the game’s existing menu architecture uses overlays.
  • Record the previous menu screen before opening.
  • Make the version control a toggle: closed opens the changelog; open returns to the previous screen.
  • Route the header toggle, visible X, bottom Back action, controller cancel, and Escape through one close or back function.
  • Use the game’s authoritative input-binding layer instead of adding a competing global Escape listener.
  • Respect higher-priority input consumers such as dialogs, drag operations, rebinding flows, and text fields.
  • Ignore repeated input and blocked transition states when the menu already does so.
  • Preserve the previous pause state when the changelog can open over gameplay.
On open, focus the close control or panel heading. On close, restore focus to the trigger when practical. Never strand keyboard or controller focus inside an unmounted panel.
将更新日志设为明确的菜单路由或屏幕状态。仅当游戏现有菜单架构使用弹窗时，才采用弹窗形式。
  • 打开前记录之前的菜单屏幕。
  • 将版本控件设为切换按钮：关闭状态下打开更新日志；打开状态下返回之前的屏幕。
  • 将头部切换按钮、可见的X按钮、底部返回动作、控制器取消键及Esc键统一路由到同一个关闭/返回函数。
  • 使用游戏的权威输入绑定层，而非添加竞争性的全局Esc监听器。
  • 尊重更高优先级的输入消费者，如对话框、拖拽操作、按键重绑定流程及文本框。
  • 若菜单已处理重复输入和阻塞状态，则更新日志也需遵循相同逻辑。
  • 若更新日志可在游戏过程中打开，需保留之前的暂停状态。
打开时，将焦点置于关闭控件或面板标题上。关闭时，尽可能将焦点恢复到触发控件。切勿让键盘或控制器焦点停留在已卸载的面板内。

Apply durable UI mechanics

应用持久化UI机制

Fit the existing game UI rather than introducing a new visual language.
  • Place the changelog control with stable menu utilities such as sound, settings, or account controls.
  • Show the current version inside the control.
  • Keep a visible close X in the panel header and give it an accessible name.
  • Keep the current-version marker and close control visible while the release list scrolls independently.
  • Render releases newest-first with semantic headings, dates, and bullet lists.
  • Keep a bottom Back action when other game panels use one.
  • Use 
    aria-expanded
    , 
    aria-controls
    , a labelled panel, and dynamic open or close labels on web-based games.
  • Preserve the version and close affordance on small screens; compact secondary text before shrinking targets.
  • Use touch targets appropriate to the game’s existing control system.
Prefer concise, specific notes such as “Restore vitality at checkpoints” over “Various fixes.” Avoid developer-only jargon unless players need it.
适配现有游戏UI，而非引入新的视觉风格。
  • 将更新日志控件放置在稳定的菜单工具区，如音效、设置或账号控件附近。
  • 在控件内显示当前版本。
  • 在面板头部保留可见的关闭X按钮，并为其设置可访问名称。
  • 版本标记和关闭控件需保持可见，即使发布列表独立滚动。
  • 按从新到旧的顺序渲染发布内容，使用语义化标题、日期及项目符号列表。
  • 若其他游戏面板使用底部返回动作，更新日志也需保留该动作。
  • 基于网页的游戏需使用
    aria-expanded
    、
    aria-controls
    、带标签的面板及动态的打开/关闭标签。
  • 在小屏设备上保留版本信息和关闭控件；先压缩次要文本，再缩小交互目标。
  • 使用与游戏现有控制系统匹配的触控目标。
优先使用简洁明确的说明，如“在检查点恢复活力”，而非“多项修复”。避免使用仅开发者能理解的术语，除非玩家需要了解。

Release safely

安全发布

Use this order:
  1. Verify the latest live version and production source.
  2. Determine the next version from the successful release stream.
  3. Implement the player-visible changes and add exactly one pending release entry.
  4. Run data, interaction, accessibility, responsive, and build checks.
  5. Commit only the intended source.
  6. Build the exact committed revision.
  7. Publish that exact revision.
  8. Confirm the deployment succeeded before calling the version released.
  9. Verify the live game shows the expected version, history count, newest entry, oldest baseline, close paths, and no runtime errors.
  10. Reconcile or stop if the deployment sequence differs from the ledger.
Do not create another changelog version merely for filling in the previous release’s provenance unless that metadata update itself is deployed to players. Bundle bookkeeping with the next real release when possible.
遵循以下顺序：
  1. 验证最新线上版本及生产源。
  2. 根据成功发布流确定下一个版本。
  3. 实现玩家可见的变更，并添加恰好一条待发布条目。
  4. 运行数据、交互、可访问性、响应式及构建检查。
  5. 仅提交预期的源内容。
  6. 基于提交的精确版本构建。
  7. 发布该精确版本。
  8. 确认部署成功后，再标记版本已发布。
  9. 验证线上游戏显示预期版本、历史条目数量、最新条目、最早基线、关闭路径，且无运行时错误。
  10. 若部署序列与账本不符，需协调解决或暂停工作。
除非元数据更新本身会部署给玩家，否则不得仅为补全上一版本的溯源信息而创建新的更新日志版本。尽可能将记录工作与下一次真实发布捆绑进行。

Validate the contract

验证契约

Require automated checks for:
  • unique, contiguous versions
  • newest-first ordering
  • oldest baseline
  • current version derived from the first entry
  • valid dates, non-empty titles, and non-empty details
  • unique deployment identifiers
  • valid or explicitly pending source revisions
  • complete rendered history in data order
  • closed and open toggle states
  • X, Back, controller cancel, and Escape using the same back route
  • focus on open and sensible focus restoration on close
  • independent list scrolling and reachable controls on small screens
Finish with production proof when the task includes a release. Test the live build, not only a local preview.
需添加自动化检查：
  • 版本唯一且连续
  • 按从新到旧排序
  • 存在最早基线
  • 当前版本从第一条条目获取
  • 日期有效、标题非空、细节非空
  • 部署标识唯一
  • 源版本有效或明确标记为待填充
  • 按数据顺序完整渲染历史
  • 切换状态正常（打开/关闭）
  • X按钮、返回动作、控制器取消键及Esc键使用同一返回路由
  • 打开时焦点正确，关闭时合理恢复焦点
  • 小屏设备上列表可独立滚动，控件可触及
若任务包含发布环节，最终需通过生产环境验证。测试线上构建，而非仅本地预览。

Avoid these failures

避免以下错误

  • Do not create one version per commit.
  • Do not show a version that has not shipped.
  • Do not let package metadata, the UI badge, and the ledger disagree.
  • Do not close to a hard-coded home screen when the player came from another menu.
  • Do not register duplicate Escape handlers that can close two layers at once.
  • Do not hide the only close control inside a long scrolling list.
  • Do not expose source hashes or deployment IDs in player-facing notes.
  • Do not rewrite historical entries without evidence.
  • 不得为每个提交创建一个版本。
  • 不得展示未发布的版本。
  • 不得让包元数据、UI徽章与账本显示不一致。
  • 当玩家从其他菜单进入时，不得关闭到硬编码的首页。
  • 不得注册重复的Esc处理程序，避免一次关闭两层界面。
  • 不得将唯一的关闭控件隐藏在长滚动列表内。
  • 不得在面向玩家的说明中暴露源哈希或部署ID。
  • 不得无证据地修改历史条目。