Warp 发布审计分类规则：如何判定公共 API 变化、废弃路径异常与语义级破坏性变更

Warp 发布审计分类规则：如何判定公共 API 变化、废弃路径异常与语义级破坏性变更

【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp

本文围绕 Warp 仓库中发布审计技能（release-audit skill）的参考文档 classification-rules.md 展开，系统讲解其定义的三类可复用分类规则：兼容性/风险记录四要素、公共 API 面判定与签名兼容性信号、废弃兼容路径的破坏性信号，以及高风险语义变更路径的识别启发式。读完本文后，你将掌握在 Warp 版本发布前，如何把一批 commit 与 CHANGELOG 片段准确归类为“真正新增的 API”“已有 API 的能力扩展”“计划内移除”或“需要告警的破坏性变更”，并理解这些规则在 SKILL.md 审计流程（Phase 3～5）中的具体落位。

分类规则在发布审计流程中的位置

Warp 仓库内置了一个 Claude 技能warp-release-audit，用于在预发布或发布候选阶段生成 markdown 审计报告，供 keep/defer 决策使用。该技能采用分阶段（Phase）加载参考文档的策略：SKILL.md 中明确声明references/classification-rules.md在Phase 3（交叉引用）、Phase 4（API 面分析）、Phase 5（CHANGELOG 语言审查）期间被加载。也就是说，本文讨论的分类规则不是孤立的检查清单，而是整个审计流水线在“给变更定性”时共享的事实基础。

技能的总体输入由仓库状态推断得出：目标版本取自 VERSION.md 并与 warp/config.py 声明的值交叉校验；base 取自上一个 minor 的最新 tag；head 优先取upstream/release-<target>，否则回落到upstream/main。分类规则随后在这条 base..head 区间内的 commit、Towncrier 渲染出的待发布条目、以及CHANGELOG.md历史数据之间做定性判断。

兼容性与风险记录：定性前的四要素

分类规则文档的第一节要求：在决定某个变更“以多高的醒目程度上报”之前，必须先记录四个事实字段：

这里有一条关键的权威性原则：以仓库自身的兼容性与废弃策略文档为准。SKILL.md 的 Phase 2 会读取 docs/user_guide/compatibility.rst 和 design/deprecations.md，把它们作为“已文档化的稳定性边界”和“计划废弃时间表”的规范定义源；若这两个文件缺失，则必须记录策略源不可用，并且不得凭文件名、符号可见性或“猜测的下游使用”编造稳定性承诺。

分类规则文档进一步给出了两条容易踩坑的边界判断：

• 源码可见性、头文件声明、或看起来面向下游的命名，都不构成支持承诺。一个符号写在warp/native/的 C++ 头文件里，不代表它被兼容性策略覆盖；只有策略文档明确承诺的接口才算受支持表面。
• 兼容事实要与其发布风险分离记录。原文的表述是：“一次调用可能因此停止编译，但它仍可能是文档化窗口已满足的计划内移除（planned removal）。” 换言之，“编译不过了”不等于“这是违规破坏”，必须结合废弃窗口来判断该记为告警还是迁移指引。

公共 API 面判定（Phase 4a / 4e）

分类规则的核心用途之一，是区分一个符号是**“真正新增（genuinely new）”还是“早已存在、只是被扩展（pre-existed and got extended）”**。这直接决定 CHANGELOG 中的Added条目最终落入报告的 “New API” 小节还是 “Changes to Existing API” 小节。

哪些路径构成 Warp 的公共 API 面

文档列出了五条路径规则，用于选择要分析哪些模块，并在辅助脚本发出警告时指导人工回退检查：

1. warp/init.py —— 顶层再导出，即用户可见的 Python 表面；
2. warp/init.pyi —— 供类型检查器和 IDE 使用的顶层公共 stub；
3. warp/_src/builtins.py —— kernel 作用域内置函数，用户面限于@wp.kernel内部；
4. 从 warp/init.py 经from warp._src.<mod> import X as X到达的任意模块；
5. warp/config.py —— 用户可见的配置标志（例如wp.config.track_memory），以及 CHANGELOG 条目中点名的公共子模块（如warp.fem、warp.optim.linear、warp.jax等），需先解析到公共包/模块（如 warp/fem/init.py、warp/optim/linear.py），再沿公共再导出追到真实源模块与匹配的.pyistub。

对照仓库源码可以印证这套路径规则的准确性：warp/init.py 确实以from warp._src.types import Float as Float这类import X as X形式组织顶层再导出（文件内还有注释说明该文件被warp._src.context.export_stubs逐行解析以生成 stub，因此每条声明必须保持单行）；warp/config.py 则以模块级带类型注解的变量暴露launch_array_access_mode、deterministic等配置标志，且通过自定义的_ConfigModule类在赋值时做类型校验（例如deterministic必须取DeterministicMode枚举值）——这些正是审计时“配置面变化”需要核对的落点。

如何判定wp.X在 base 时是否已存在

文档给出了按符号类别分流的 base 状态查询方法，全部基于git show <base>:<path>的静态检查：

• 顶层符号：git show <base>:warp/__init__.py，grep 是否有import X as X；
• 子模块属性：读取 base 时该子模块的源码（如git show <base>:warp/_src/utils.py），查找属性定义；
• kernel 内置函数：git show <base>:warp/_src/builtins.py，grepadd_builtin("<name>"；
• 公共子模块 API：在 base 与 HEAD 两处分别解析公共函数、公共类、类__init__方法、公共方法（非下划线开头名称）；
• 公共 stub：解析.pyi文件，对比公共函数、类、方法、overload 变体、模块级带注解属性与导出别名。特别强调：若一个仅存在于 stub 中的公共符号在 base 存在而在 HEAD 消失，即使运行时源码没变，也要报告“公共 stub 移除”。

第三条规则在仓库中可以找到直接证据：warp/_src/builtins.py 以统一的add_builtin("name", input_types={...}, value_func=..., doc=..., group=...)调用注册每一个内置函数（文件内此类调用超过数百处），例如add_builtin("min", input_types={"a": Scalar, "b": Scalar}, ...)。这意味着“某内置函数在 base 是否存在”可以用一次针对add_builtin("min"这样的模式匹配确定性地回答，这正是分类规则选择静态 grep 而非运行时的原因。

签名形状的破坏性与非破坏性信号

文档把“签名形状变化”分为两组信号，这是审计时对Changed条目渲染 diff 的核心判据：

通常属于破坏性（Breaking）的信号：

• 新增必填参数，且没有保留旧调用形式的 overload/包装；
• 参数被移除、重命名或重新排序；
• 既有的 positional-or-keyword 参数被移到*之后（positional 变 keyword-only）；
• 新的 positional-or-keyword 参数被插入到所有既有 positional-or-keyword 参数之前——即使带默认值，因为旧的位置调用会绑定到不同参数上；
• 公共 stub 中的符号、overload、方法或属性从.pyi中被移除。

通常属于非破坏性的信号：

• 新的带默认值的 positional-or-keyword 参数追加在所有既有 positional-or-keyword 参数之后；
• 新的带默认值的 keyword-only 参数。

这条规则背后是 Python 调用绑定语义：只有“追加在末尾的带默认参数”能同时兼容位置调用与关键字调用，而“前置插入带默认参数”虽然不报错，却会静默改变旧位置调用的绑定目标——这正是审计中最需要人工警觉的隐性破坏。

diff_public_api.py：Phase 4e 的机械化执行

Phase 4e 要求先运行 scripts/diff_public_api.py 并消费其 JSON 事实，再做上述路径规则的人工回退。从脚本源码可以看到它与分类规则的严格对应关系：

uv run "<skill-dir>/scripts/diff_public_api.py" \ --base <base-ref> \ --head <head-ref> \ \--module warp \ --module <public-submodule>

脚本 diff_public_api.py 是有意保持“静态、仅标准库”的工具：它从 git ref 读取源码文件、用ast解析模块表面（ModuleSurface数据结构按符号聚合ApiEntry，参数用Param(name, kind, has_default)建模），最终输出Change(kind, symbol, surface, reasons, breaking, base, head, source)结构的 JSON 变更列表。它不导入 Warp、不构建原生库，因此可以在任意工作机上对任意 base/head ref 对运行，为审计提供确定性的运行时签名与 stub 移除事实。脚本对包模块的解析先尝试<module>/__init__，再尝试单文件模块，与上文路径规则中“先解析公共包，再追真实源模块”的流程一致。

废弃兼容路径的破坏性信号（Phase 4f）

这一节专门捕捉一类容易被漏掉的破坏：旧导入路径或兼容包装器仍然存在、仍会发出弃用警告并转发到替代 API，但新版本悄悄收紧了它。文档先给出候选路径的识别方法：

• 文件名或包名包含deprecated、deprecation、compat、compatibility、backcompat的文件/包；
• 出现在Deprecated、Removed或迁移类 CHANGELOG 条目中点名的公共模块；
• 从旧命名空间发警告并把导入转发到替代命名空间的模块。

然后列出在该路径上 base→HEAD 的破坏性信号：

1. 废弃路径中新出现的raise语句；
2. 在到达替代 API 之前，异常类型或异常消息发生了改变；
3. 转发/委托之前出现更严格的守卫条件；
4. 移除了围绕旧导入或兼容别名的try/except回退；
5. 在原本“警告并委托”的路径上新增了导入期错误。

对应的报告动作是：生成一条 Breaking Changes 条目，外加一条 kind 为semantic change、描述为 “new exception in deprecated compatibility path” 的 Changes-to-Existing-API 行，并附上 before/after 片段说明用户应改调的替代路径。文档特别强调：不能仅因路径已废弃就抑制该发现——一个已文档化、仍受支持的兼容路径，在计划移除日期之前承担着迁移契约；而内部或不支持的兼容辅助则不承担。这与前文“兼容事实与发布风险分离记录”的原则一脉相承。

语义级变更的发现提示

文档明确声明：下面这些路径只是高风险提示（high-risk hints），不是穷举范围，并且“高风险路径中的变更并不都是破坏性的”。当待发布条目或 diff 合理可能改变受支持、可观察的行为时，还应检查其他路径。

高风险路径：

• warp/_src/codegen.py—— Python 代码生成；变更可能改变最终发射的 CUDA/CPU 代码；
• warp/native/**—— C++/CUDA 源码；变更可能改变运行时数值行为或 ABI。

这些路径中典型的非破坏性信号：

• 纯内部重构、内部标识符改名；
• 注释或格式变更；
• 保持可观察输出不变的性能优化；
• 构建系统改动（CMake 标志、编译依赖）；
• 仅测试的变更；
• 修复了此前可证明是错误行为的 bug。

当受影响的表面受支持且可达时，典型的破坏性信号：

• 影响数值结果的发射指令或寄存器分配变化；
• 改变语义的默认编译器标志变化；
• 影响兼容性策略所覆盖 ABI 的 struct 布局变化；
• 产生不同数值结果的算法替换；
• 改变用户代码被调用时机或频率的控制流变化。

结合 SKILL.md 的 Phase 4g 可以看到这些提示的闭环：对“仅凭 diff 无法确定用户是否可观察”的模糊候选，审计者必须实际在 base 与 HEAD 两个构建上运行最小复现脚本（用uv run build_lib.py --quick构建），比较可观察输出后才决定是否上报——“未经验证的标记不得进入报告”。分类规则文档提供了“去哪里找风险”，Phase 4g 规定了“如何验证风险”，两者共同保证了报告中每一条 Breaking Changes 都有明确证据来源。

仅用于模式识别的启发式路径

文档最后一节声明：以下路径列出是为了让审计者在读 commit 时能够“模式识别”，但技能并不用它们生成“缺少 CHANGELOG 条目的 commit”审计痕迹——识别，而非分桶：

• .github/**、.gitlab-ci.yml、.gitlab/**、tools/**、.pre-commit-config.yaml、uv.lock、.python-version—— 基础设施，非用户可见；
• asv.conf.json、benchmarks/**—— 基准测试框架；
• docs/**、根目录*.md—— 文档；
• 除codegen.py外的warp/_src/**—— 内部 Python 实现；
• warp/native/**—— 原生代码（仍须按上一节的语义破坏分析对待）。

对照仓库结构，这些启发式与实际情况吻合：tools/下是 CI 构建与 LLVM 打包工具，asv/benchmarks/是 ASV 基准测试套件，docs/是 Sphinx 文档树，而warp/native/下聚集了bvh.cu、reduce.cu、tile.h、sparse.cu等 C++/CUDA 实现——这些文件的变化确实需要按“语义级高风险路径”而非普通内部代码来审视。

小结

classification-rules.md 用不到两百行定义了一套可执行的发布审计分类学：以 Surface/Reachability/Deprecation/Action 四要素为定性前提，以五条公共 API 路径规则加 base 状态查询为“新 vs 扩展”的判据，以签名形状两组信号区分真破坏与兼容扩展，以废弃路径的五类信号捕捉迁移契约的隐性破裂，再以warp/_src/codegen.py与warp/native/**两个高风险提示区引导语义级验证。这些规则与 scripts/diff_public_api.py 的确定性 JSON 输出、SKILL.md 中 Phase 4g 的“跑代码验证”要求相互配合，共同保证 Warp 每次发布审计报告中，每一条破坏性变更结论都对应明确的源码级证据，而不是一次模糊的 diff 印象。

【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp