build-game-changelog

ゲームの変更履歴を構築する

変更履歴は、装飾的なモーダルではなく、リリースシステムとして構築してください。唯一の信頼できる台帳を、本番環境の履歴、ゲームメニューのナビゲーション、リリース検証と連携させます。

このメンタルモデルを使う

• 台帳は、プレイヤーが受け取ったものを記録する公開情報です。
• バージョンは、開発中のコミットではなく、成功した本番リリースを識別します。
• 台帳の最新エントリが、ゲーム全体に表示されるバージョンを決定します。
• 変更履歴を開く操作は、元に戻せるメニュー状態の遷移です。
• すべての閉じる操作は、同じ戻るアクションを経由します。
• ライブゲームで期待どおりのバージョンと動作が確認されて初めて、リリースは完了です。

事実から始める

編集する前に調査します。

1. リポジトリの指示を読み、無関係な作業には手を加えないでください。
2. ゲームのメニューまたは一時停止の状態機械、戻るアクション、入力バインド、フォーカス動作、レスポンシブレイアウトを確認します。
3. 表示されているすべてのバージョン、パッケージのバージョン、ビルドバージョン、デプロイの順序、リリースマニフェスト、既存の変更履歴を確認します。
4. 可能であれば、成功した本番デプロイとそのソースリビジョンを照会します。
5. デプロイのリビジョンを比較し、プレイヤーが実際に受け取った内容を特定します。

チャットの要約やコミットメッセージからの推測より、リポジトリ、デプロイ、ライブ実行時の証拠を優先してください。欠落しているリリース日、ソースリビジョン、機能、バージョンの対応関係を捏造しないでください。

1つのリリースを定義する

プレイヤーに見える、本番環境へのデプロイが成功するたびに、1つの変更履歴バージョンとして扱います。

• ローカルコミット、ドラフト、テスト、失敗したビルド、保存済みでも未公開の成果物では、バージョンを上げないでください。
• 一緒にリリースされた複数のコミットは、複数のリリースノートを含む1つのバージョンにまとめます。
• 別途デプロイされたホットフィックスには、独自のバージョンを付けます。
• 実装上の作業や生のコミットメッセージではなく、プレイヤーに見える結果を記述します。
• 内部のソース識別子とデプロイ識別子は、プレイヤー向けの文面ではなく台帳のメタデータに保持します。

既存のバージョン方式を維持してください。バージョン方式がない新規の1.0未満のゲームでは、デフォルトで 0.9.0 を使用し、本番リリースごとにパッチを1つずつ増やします。例：0.9.1、0.9.2 など。明示的な製品マイルストーンがない限り、新しいマイナーまたはメジャーバージョンに飛ばさないでください。

台帳を構築または補完する

履歴を再構築するときは古い順に作業し、表示用には新しい順にエントリを保存します。

1. 成功した本番リリースを列挙します。
2. 各リリースを、その日付、デプロイされたソースリビジョン、デプロイ識別子に関連付けます。
3. 各ソースリビジョンを、直前の本番リビジョンと比較します。
4. そのリリースにおける、ユーザーに見える変更を要約します。
5. デフォルト方式を採用する場合、最初の本番ベースラインを 0.9.0 とします。
6. デプロイ追跡の導入前に行われた、意義のあるローンチ作業はベースラインにまとめます。
7. 台帳の件数、並び順、一意性、バージョンの連続性を検証します。

証拠が不完全な場合は、内部メタデータに出所不明と記録するか、確認を求めて作業を止めてください。整然とした履歴を捏造しないでください。

データソースを1つにする

変更履歴の内容は、型付きまたはスキーマ検証済みの構造化データとして保持します。各エントリには次の情報を含めます。

• バージョン
• リリース日
• 短いリリースタイトル
• プレイヤー向けの詳細を1つ以上
• 入手可能な場合はデプロイバージョンまたはリリース識別子
• 入手可能な場合は正確なソースリビジョン

表示する現在のバージョンは、台帳の最新エントリから導出します。手書きのバージョン定数を別途管理しないでください。

ゲームのバージョンとデプロイバージョンの明示的な対応関係を保存します。patch = deploymentOrdinal - 1 のような式を使うのは、プロジェクトでその対応が保証され、テストされている場合に限ります。

ソースメタデータが自己参照にならないようにしてください。コミットに、そのコミット自身の最終ハッシュを含めることはできません。次のいずれかを選んでください。

• 最新のインラインエントリのソースリビジョンを保留にし、次回のリリース時に補完する。
• ビルド時に正確なリビジョンを注入する。
• 不変のリリース出所情報をソースコミットの外部に保存する。

スキーマ、状態機械、テストを実装する際は、references/reference-architecture.md を参照してください。

ゲームのナビゲーションと統合する

チェンジログを明示的なメニュールートまたは画面状態にします。ゲームの既存のメニューアーキテクチャがオーバーレイを使用している場合にのみ、オーバーレイを使用してください。

• 開く前に、直前のメニュー画面を記録します。
• バージョン管理をトグルにします。閉じた状態ではチェンジログを開き、開いた状態では前の画面に戻ります。
• ヘッダーのトグル、表示される X、下部の Back アクション、コントローラーのキャンセル、Escape を、単一の閉じるまたは戻る関数を経由させます。
• 競合するグローバルな Escape リスナーを追加するのではなく、ゲームの権威ある入力バインディングレイヤーを使用します。
• ダイアログ、ドラッグ操作、再バインドのフロー、テキストフィールドなど、より優先度の高い入力コンシューマーを尊重します。
• メニューがすでにそうしている場合は、繰り返し入力とブロックされた遷移状態を無視します。
• チェンジログをゲームプレイの上に開ける場合は、以前の一時停止状態を維持します。

開いたときは、閉じるコントロールまたはパネルの見出しにフォーカスします。閉じたときは、実用的であればトリガーにフォーカスを戻します。アンマウントされたパネル内にキーボードまたはコントローラーのフォーカスを置き去りにしないでください。

堅牢な UI メカニクスを適用する

新しい視覚言語を導入するのではなく、既存のゲーム UI に合わせます。

• チェンジログのコントロールは、サウンド、設定、アカウントなどの安定したメニューユーティリティとともに配置します。
• コントロール内に現在のバージョンを表示します。
• パネルのヘッダーに、アクセシブルな名前を付けた、表示される閉じる X を維持します。
• リリースリストが独立してスクロールしている間も、現在のバージョンのマーカーと閉じるコントロールを表示したままにします。
• リリースは新しい順に、セマンティックな見出し、日付、箇条書きでレンダリングします。
• 他のゲームパネルが下部の Back アクションを使用している場合は、それを維持します。
• Web ベースのゲームでは、aria-expanded、aria-controls、ラベル付きのパネル、動的な開閉ラベルを使用します。
• 小さい画面でもバージョンと閉じるアフォーダンスを維持します。ターゲットを縮小する前に、二次的なテキストをコンパクトにします。
• ゲームの既存のコントロールシステムに適したタッチターゲットを使用します。

「Various fixes」よりも、「Restore vitality at checkpoints」のような簡潔で具体的な注記を優先してください。プレイヤーが必要としない限り、開発者専用のジャーゴンは避けてください。

安全にリリースする

次の順序を使用します。

1. 最新のライブバージョンと本番ソースを検証します。
2. 成功したリリースストリームから次のバージョンを決定します。
3. プレイヤーに見える変更を実装し、保留中のリリースエントリをちょうど 1 つ追加します。
4. データ、インタラクション、アクセシビリティ、レスポンシブ、ビルドのチェックを実行します。
5. 意図したソースのみをコミットします。
6. コミットされた正確なリビジョンをビルドします。
7. その正確なリビジョンを公開します。
8. バージョンがリリースされたとみなす前に、デプロイが成功したことを確認します。
9. ライブゲームが、期待されるバージョン、履歴数、最新エントリ、最古のベースライン、閉じる経路を表示し、ランタイムエラーがないことを検証します。
10. デプロイの順序が台帳と異なる場合は、調整するか停止します。

そのメタデータ更新自体がプレイヤーにデプロイされない限り、前回のリリースの来歴を埋めるためだけに別のチェンジログバージョンを作成しないでください。可能な場合は、帳簿管理を次の実際のリリースにまとめてください。

コントラクトを検証する

次の項目について自動チェックを必須とします。

• 一意で連続したバージョン
• 新しい順の並び
• 最古のベースライン
• 最初のエントリから導出される現在のバージョン
• 有効な日付、空でないタイトル、空でない詳細
• 一意のデプロイ識別子
• 有効な、または明示的に保留中のソースリビジョン
• データ順での完全なレンダリング済み履歴
• 閉じた状態と開いた状態のトグル
• 同じ戻るルートを使用する X、Back、コントローラーのキャンセル、Escape
• 開いたときのフォーカスと、閉じたときの適切なフォーカス復元
• 独立したリストスクロールと、小さい画面で到達可能なコントロール

タスクにリリースが含まれる場合は、本番環境での証明で締めくくります。ローカルのプレビューだけでなく、ライブビルドをテストしてください。

これらの失敗を避ける

• コミットごとにバージョンを作成しないでください。
• リリースされていないバージョンを表示しないでください。
• パッケージのメタデータ、UI のバッジ、台帳の内容を食い違わせないでください。
• プレイヤーが別のメニューから移動してきた場合に、固定されたホーム画面へ戻さないでください。
• Escape キーのハンドラーを重複して登録し、一度に 2 つのレイヤーが閉じることのないようにしてください。
• 唯一の閉じる操作を、長いスクロールリストの中に隠さないでください。
• プレイヤー向けのリリースノートに、ソースハッシュやデプロイ ID を表示しないでください。
• 根拠がないまま、過去のエントリーを書き換えないでください。