Build Game Changelog

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.

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.

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.

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.

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.