megatron-change-analyzer

Megatron 变更分析器

将原始 Megatron 变更集转化为结构化的特性演进发现，为后续实现工作做好准备。重点是提取上游特性的实际形态，而不是编写 MindSpeed 代码。

核心规则

• 假设输入是经过规范化的 Megatron change-set，而非任意一组提交。
• 如果多个底层提交服务于同一特性，则将其归并为更高层级的变更事件。
• 优先关注新特性、API 形态变更、配置或 CLI 架构变更，以及会影响行为的重构。
• 为每个事件标注迁移相关性，但不要在此处修改 MindSpeed。
• 将上游提交本身视为实现证据，而不仅仅是摘要来源。
• 如果某项特性由特定提交或紧密相关的提交集群构成，则保留该分组，以便后续步骤能以提交为主要参考移植实现。
• 将 megatron main 中的发现视为探索性内容，除非用户提供了严格的目标映射。

输出格式

生成一份结构化报告，每项特性或与迁移相关的变更对应一个事件：

{
  "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. 适当时将相关提交合并为一个事件，同时保留主要实现提交。
4. 使用 change-taxonomy.md 中的分类体系为每个事件标注。
5. 将每个相关事件拆分为实现单元： 配置和 CLI 接入， 运行时逻辑， 包装器或适配器， 测试和示例， 生命周期或清理行为。
6. 将事件分为以下几类： 与 MindSpeed 相关， 可能已涵盖， 目前不值得适配。
7. 仅将相关子集交给影响映射器，并附上提交引用、上游变更文件和实现单元。

需要重点关注

• 新增的功能或工作流
• 公共 API 新增内容或签名变更
• CLI/配置项的新增、移除或重命名
• 检查点或状态格式变更
• 并行和分布式执行变更
• 数据流水线或运行时行为变更

应避免的事项

• 不要在此处生成代码补丁。
• 不要仅凭 Megatron 证据断言与 MindSpeed 兼容。
• 除非内部重构改变了集成接口，否则不要将其视为高价值迁移工作。
• 如果上游提交实际改变了多个集成接口，不要将大型特性压缩成一句话说明。保留足够的结构，供后续实现使用。

参考资料

• 为事件分类前，请阅读 change-taxonomy.md。
• 需要生成保留主要提交、上游变更文件和实现单元的确定性首轮事件文件时，请运行 build_feature_events.py。
• 将与迁移相关的事件交给 $megatron-impact-mapper。