megatron-change-analyzer

Megatron 変更アナライザー

未加工の Megatron 変更セットを、後続の実装作業にすぐ活用できる、構造化された機能進化の分析結果に変換します。MindSpeed のコードをまだ作成するのではなく、上流機能の実際の形を抽出することに重点を置きます。

基本ルール

• 入力は、任意のコミットの寄せ集めではなく、正規化された Megatron の change-set であることを前提とします。
• 複数の低レベルのコミットが1つの機能に関わる場合は、より高レベルの変更イベントにまとめます。
• 新機能、API の形状変更、設定または CLI スキーマの変更、動作に影響するリファクタリングを優先します。
• 各イベントに移行上の関連性を付与しますが、ここでは MindSpeed を編集しません。
• 上流のコミット自体を実装の根拠として扱い、単なる要約の情報源として扱わないでください。
• 機能が特定のコミット、または密接に関連するコミット群で表現されている場合は、そのまとまりを維持し、後続の工程でコミットを主要な参照元として実装を移植できるようにします。
• ユーザーが厳密なターゲットマッピングを提示していない限り、megatron main の分析結果は探索的なものとして扱います。

出力形式

機能または移行に関連する変更ごとに1つのイベントを含む、構造化レポートを作成します。

{
  "branch": "core_v0.15.3",
  "events": [
    {
      "title": "Add feature X",
      "kind": "new_feature",
      "commits": ["sha1", "sha2"],
      "primary_commit": "sha2",
      "areas": ["training", "config"],
      "breaking_risk": "medium",
      "migration_relevance": "high",
      "notes": "Short factual summary",
      "evidence": ["file/path.py", "arguments.py"],
      "upstream_changed_files": ["megatron/path_a.py", "megatron/path_b.py"],
      "implementation_units": [
        {
          "name": "Expose new config flag",
          "kind": "config_surface",
          "upstream_files": ["megatron/training/config/training_config.py"],
          "summary": "What this unit changes in upstream code"
        },
        {
          "name": "Add runtime behavior",
          "kind": "runtime_logic",
          "upstream_files": ["megatron/training/global_vars.py"],
          "summary": "What runtime path must be ported downstream"
        }
      ],
      "porting_notes": [
        "Facts the downstream mapper should preserve when porting the feature"
      ]
    }
  ]
}

ワークフロー

1. 正規化された変更セットを読みます。
2. 機能レベルでコミットタイトル、変更されたファイル、差分を調べます。
3. 適切な場合は関連するコミットを1つのイベントにまとめますが、主要な実装コミットは明示したままにします。
4. change-taxonomy.md の分類体系を使って各イベントにラベルを付けます。
5. 関連する各イベントを、次の実装単位に分けます。 設定と CLI への公開、 ランタイムロジック、 ラッパーまたはアダプター、 テストとサンプル、 ライフサイクルまたはクリーンアップの動作。
6. イベントを次のように分類します。 MindSpeed に関連するもの、 すでに対応済みと思われるもの、 現時点で適応する価値がないもの。
7. 関連するイベントだけを、コミット参照、上流で変更されたファイル、実装単位とともに、影響マッパーに引き渡します。

注目すべき点

• 新たに公開された機能やワークフロー
• 公開 API の追加やシグネチャの変更
• CLI／設定の追加、削除、名称変更
• チェックポイントまたは状態形式の変更
• 並列処理および分散実行の変更
• データパイプラインまたはランタイムの動作変更

避けるべきこと

• ここではコードパッチを作成しないでください。
• Megatron の根拠だけで MindSpeed との互換性があると断定しないでください。
• 統合面に変更をもたらさない内部リファクタリングを、重要度の高い移行作業として扱わないでください。
• 上流のコミットが複数の統合面を実際に変更している場合、大規模な機能を一行のメモにまとめないでください。後続の実装に必要な構造を十分に残してください。

参照資料

• イベントにラベルを付ける前に、change-taxonomy.md を読みます。
• 主要なコミット、上流で変更されたファイル、実装単位を保持する決定的な初回イベントファイルが必要な場合は、build_feature_events.py を実行します。
• 移行に関連するイベントは、$megatron-impact-mapper に引き渡します。