Newton 发布审计分类规则全解公共 API 表面、语义变化与弃用政策判定【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton本篇技术指南以 Newton 开源仓库基于 NVIDIA Warp 的 GPU 加速物理仿真引擎中.claude/skills/release-audit发布审计技能的分类规则参考文档classification-rules.md为核心骨架系统讲解如何判定一个符号是否是真正新增的公共 API、哪些代码路径的改动会被判定为语义变化、以及移除 API 前必须满足的弃用窗口证据。读完本文你将掌握 Newton 项目发布审计Release Audit中分类环节的完整方法论能够对照源码如 docs/generate_api.py、newton/init.py、newton/solvers.py独立执行 API 差异分析与破坏性变更判定。一、classification-rules 在审计流程中的定位在 Newton 仓库中发布审计由一个名为release-audit的 Claude 技能驱动其主流程定义在 SKILL.md 中。该技能覆盖三种模式预发布Pre-release、发布候选RC与回溯审计Retrospective最终产出一份 Markdown 格式的审计报告模板见 report-template.md。classification-rules.md正是这个技能在Phase 3、4、5交叉引用、API 表面分析、语言审查阶段加载的核心参考它定义了两类 Claude 依赖的具体规则路径规则path rules哪些目录被触碰时提交需要逐条人工判定命名规则naming rules如何判定一个符号是真正新增还是先前已存在并扩展以及如何识别 Newton 特有的重命名/参数重排模式。审计报告呈现时还受 render-rules.md渲染约束与 language-review-examples.md语言审查校准两份参考约束前者负责输出样式后者负责 CHANGELOG 措辞的审查基准。二、公共 API 表面判定没有固定的 MODULES 常量2.1 动态发现机制Newton 没有像 Warp 那样的单一__init__.py集中导出也没有一个写死的MODULES常量。公共表面通过**按主题划分的再导出模块re-export modules**暴露并由docs/generate_api.py动态发现。审计时必须在 base 与 target 两个 ref 上都运行下述发现规则api_modules()导入newton顶层模块遍历newton.__all__中所有模块值module-valued的导出每个以newton.开头的模块都会被加入候选列表。对应源码见 docs/generate_api.py。public_symbols()读取每个被发现的模块自身的__all__列表或元组拒绝缺失声明、非法容器和非字符串条目。对应源码见 docs/generate_api.py。solver_submodule_pages()额外把newton.solvers下公开的求解器子模块及其递归暴露的模块树加入文档生成列表但只保留暴露了不止求解器类本身的子模块_is_solver_only_module会过滤掉仅含单个Solver*类的模块。对应源码见 docs/generate_api.py。以实际仓库为例newton/__init__.py中__all__既包含直接再导出的符号SDF、Mesh、Model、ModelBuilder、State、Solver相关eval_*函数等也包含 11 个公共子模块actuators、controllers、geometry、ik、math、selection、sensors、solvers、usd、utils、viewer见 newton/init.py 与 newton/init.py。每个公共模块再各自从newton/_src/topic/...内部实现中挑选符号公开例如 newton/geometry.py 的__all__列出了BroadPhaseSAP、NarrowPhase、HydroelasticSDF、ParticleSurface以及一组collide_*、sdf_*函数。2.2 判定base 时是否存在的四条检查路径对每个 CHANGELOGAdded条目中提取出的符号按如下规则核对 base ref符号层级检查方法顶层模块newton.Xgit show base:newton/__init__.py检查from ._src.submodule import X与__all__子模块公开属性如newton.geometry.Meshgit show base:newton/geometry.py检查 import 与__all__嵌套求解器模块用solver_submodule_pages()的可达性规则套用到 base 的newton.solvers已有类的新增方法如SolverXPBD.update_contacts定位类的真实源码文件如newton/_src/solvers/xpbd.py在 base 上用ast遍历类体特别地newton.solvers本身是一个模块而非包它在__all__中并入_src.solvers的全部符号并额外暴露一个懒加载的experimental.coupled命名空间见 newton/solvers.py。这意味着审计新增的嵌套实验性求解器命名空间时必须同时检查newton.solvers.experimental的模块树结构。2.3 公开声明与暴露检查Phase 4a 附加步骤审计新增符号时还要对 HEAD 的每个公共模块做一次完整性校验每个公共模块的__all__必须是仅含字符串的列表或元组否则属于策略违规对每个真正新增的符号收集它在所有公共模块__all__中的出现次数0 次触发 ️ Private-only 标记——符号只存在于newton._src.*未通过公共模块再导出1 次确立唯一的规范化公共导入路径多次触发重复公开导出duplicate-public-export策略发现需列出所有导出它的公共模块。这条规则直接源于 CODING_GUIDELINES.rst 的硬性要求每个公共符号必须恰好出现在一个公共模块的__all__中且示例与文档禁止从newton._src导入newton._src是内部命名空间可被 Python 访问但不受稳定承诺保护。newton.geometry中的MATCH_BROKEN/MATCH_NOT_FOUND就是兼容性导出的典型——它们通过__deprecated_symbols__声明为仅警告的兼容名并在__getattr__中触发DeprecationWarning见 newton/geometry.py这类兼容别名是弃用政策的明确例外。三、无内核作用域内建注册表Warp 存在add_builtin()这类内核作用域内建注册表供审计而Newton 没有对应的独立注册表。Newton 的全部用户可见符号都是定义在newton/_src/**中的普通 Python 类、函数、枚举与常量再经由公共模块再导出。因此Phase 4b 提取签名时ast.parse源码模块后直接查找FunctionDef/ClassDef/AsyncFunctionDef即可无需额外的符号解析层审计流程可以跳过内核作用域符号提取这一步直接进入公共模块__all__的核对。这一点也解释了为何 generate_api.py 只用inspectimportlibpkgutil就能完成全部 API 文档生成——整个公共表面就是纯 Python 模块树。四、触发语义变化审查的路径Phase 4f4.1 四条核心路径触碰以下路径的提交需要逐条人工判定Phase 4f但不是所有改动都是语义变化——Claude 需要阅读 diff 后自行裁决路径影响面newton/_src/solvers/**求解器实现XPBD、MuJoCo、Featherstone、VBD、implicit MPM改动可能改变收敛性、接触处理与 step 语义newton/_src/sim/**积分器、碰撞管线、模型构建、状态传递改动可能改变每步动力学或接触顺序newton/_src/math/**数学辅助、射线投射、四元数工具改动可能改变数值输出newton/_src/geometry/**几何图元、SDF/网格表示、支撑函数改动可能改变接触法线、距离或内/外测试4.2 典型信号对照表通常 NOT-SEMANTIC-SHIFTING不构成语义变化纯内部重构、内部标识符重命名注释或格式改动保持可观察输出的性能优化如向量化、预计算 AABB缓存/记忆化且缓存值等价仅测试改动构建系统触碰修复先前行为已被证明是错误的 bug。典型 SEMANTIC-SHIFTING构成语义变化产生不同数值结果的算法替换例如 SDF 构建从 winding-number 切换为 parity影响物理的默认参数值变化如 MPM 求积、接触刚度、求解器迭代默认值影响接触约简或约束求解的顺序/确定性变化收敛判据变化不同容差、不同迭代上界行为作者输入值的单位/参考系变化例如停止将关节阻尼乘以 180/π改变回调/注册钩子/用户内核调用时机的控制流变化。4.3 明确的禁止项不做 base 与 HEAD 的构建对比验证规则明确指出永远不要尝试在 base 与 HEAD 上构建并运行 Newton 来做数值验证。因为 Newton 的输出依赖 Warp 代码生成、MuJoCo 与 GPU 状态一次性审计中做可靠的 head-to-head 数值对比超出范围。当 Claude 无法仅凭阅读 diff 判断用户是否会感知到变化时该提交应进入报告 review notes 的Review candidates小节而不是在 Breaking Changes 中推测。五、启发式路径分类仅作识别参考以下路径映射用于帮助 Claude 在阅读提交时快速模式匹配技能不会据此生成附录式的提交审计其目的是识别而非归类.github/**、.pre-commit-config.yaml、uv.lock、.python-version—— 基础设施非用户可见asv.conf.json、asv/**、根级_bench_*.py—— 基准测试框架docs/**、根级*.md、CHANGELOG.md、changelog/**—— 文档newton/examples/**—— 示例脚本新文件属于用户可见新示例是发布值得记录的添加项对现有示例的修改通常不值得记录除非改变注册名或行为上述四条路径之外的newton/_src/**—— 内部 Python 实现pyproject.toml、uv.lock与project.license-files匹配的文件 —— 依赖与许可证审计输入。新增外部依赖名、直接依赖范围变化、新增解析包名与通知文件变化属于Dependency License Audit单纯版本升级本身不值得记录但用户可见的 pin 移动如mujoco-warp ~3.7.0可能同时进入Behavioral Support Changes。仓库中真实的 changelog fragment 目录changelog/印证了这套分类joint-mimic-metadata-8e61c4a2.added.md、deformable-collision-block-size-6f2a9c1d.changed.md、mujoco-joint-reference-7c4e2a91.deprecated.md、model-collision-filters-2f6c8a1d.removed.md、kamino-type-error-008d8f13.fixed.md分别对应五种分类命名规则issue.TYPE.md或slug-random.TYPE.md在 changelog/README.md 中有完整说明。六、Newton 特有的重命名与参数重排识别Phase 4d/5a6.1 无**Breaking:**标记的破坏性变更识别与 Warp 不同Newton 的 CHANGELOG 不使用**Breaking:**字面标记。需要迁移的变更出现在### Changed中并带有以下典型措辞模式Rename X.old_name to X.new_name. Old name still accepted as keyword argument but emits a DeprecationWarning.重命名旧名仍可作为关键字参数接受但发出DeprecationWarningReorder X() parameters so a precedes b.参数重排Migrate all Y logic to Z, all Y functions now return ...行为迁移。Phase 4d/5a 遇到这些模式时应将它们视为 Kind 为rename或parameter reorder的迁移必需变更并核对条目是否包含迁移指引Use ...、in favor of ...、prefer ...若缺失在语言审查中触发 ⬆️ 标记。6.2 源码层的运行时弃用证据仓库在 newton/_src/utils/deprecation.py 中提供了deprecate_nonkeyword_arguments装饰器它通过inspect.signature统计位置参数数量当调用者把 keyword-only 参数以位置参数传入时发出DeprecationWarningPassing xxx positionally to func() is deprecated...。该文件还包含RemovedAttributeError描述符类用于在移除属性访问时抛出带替换指引的AttributeErrorxxx was removed in Newton X; use yyy instead.。审计 Phase 4d 在找不到已发布 CHANGELOG 弃用条目时正是通过这类代码级证据确认用户是否实际收到了弃用窗口。6.3 实验性标记交叉引用Phase 4g对每个 Breaking / Changed / Removed 条目审计还会检查受影响符号是否带experimental标记先在已发布版本段的 CHANGELOG 中搜索含experimental字样的引入条目再检查源码 HEAD 是否存在.. experimental/Experimental:/experimental_api/experimental注解。实验性符号的稳定性契约更宽松其破坏性条目渲染为Experimental:前缀不带警告 emoji在 Changes-to-Existing-API 表中 Breaking 列显示Experimental且实验性状态本身不构成发布亮点。七、弃用政策与三类裁决结果Phase 4dCODING_GUIDELINES.rst 规定破坏性变更必须先弃用。因此每个 Removed 条目都需要先前已弃用的证据证据来源按优先级为已发布版本 CHANGELOG 中匹配的### Deprecated条目base ref 处匹配的运行时DeprecationWarning——无论警告是直接warnings.warn发出还是由明确作用于被移除 API 的共享辅助函数/装饰器如deprecate_nonkeyword_arguments发出两者皆无 —— 触发 Policy: removed without prior deprecation。规则特别强调三点取证边界共享辅助函数本身的存在或导入不算证据必须验证候选调用点把辅助函数连接到了被移除的具体 API/行为且辅助函数确实为该调用模式发出DeprecationWarning不能仅凭 CHANGELOG 证据推断政策违规——代码级检查是拉起阻塞性标记前的强制步骤若运行时警告存在但已发布 CHANGELOG 遗漏了 Deprecated 条目不判定违规只记录非阻塞的文档缺口标记。唯一例外是1.0.0含1.0.0rcN的 pre-stable 清理带1.0-release标签的 PR 属稳定前 API 清理无需经过先弃用窗口。审计报告最终应向发布经理呈现三种已裁决结果之一找到先前 CHANGELOG 条目 → 报告其发布版本base 处找到运行时DeprecationWarning→ 弃用政策已满足附带非阻塞的 CHANGELOG 文档标记两者皆无 → 阻塞发布或再增加一个发布周期的弃用 shim。同时报告须在 Breaking Changes 条目与 Changes-to-Existing-API 行两处都标注弃用窗口信息如Deprecated in 1.0.0; removed here.确保读者永远无需追问是否先弃用过、弃用了多久。回溯模式下Phase 6 还会额外核对后续小版本是否真正移除了本版本 Deprecated 的符号Deprecation follow-through产出 Followed through / Still deprecated / Silently dropped 三态结论。八、总结分类规则如何驱动一份可信的发布审计将本规则文档与 SKILL.md 的七阶段流程对照可以清晰看到分类规则的作用链条Phase 2-3收集提交与 CHANGELOG 条目后Phase 4a/4e用动态 API 表面发现 四类符号存在性检查 __all__成员资格统计确定真正新增的公共 APIPhase 4f用四条核心路径solver/sim/math/geometry与语义变化信号对照表识别签名未变但数值行为可能变化的提交且严守不做 base/HEAD 数值对比的边界Phase 4d/5a用 Newton 特有的无**Breaking:**措辞识别、deprecate_nonkeyword_arguments等运行时证据以及三类裁决结果落实先弃用后移除的发布政策最终所有分类结果汇入 report-template.md 的 New API / Breaking Changes / Changes to Existing API / Behavioral Support Changes 各小节供发布经理做出 keep/defer 决策。这套规则的价值在于它把什么是破坏性变更从主观判断变成了可复现的取证流程——每条结论都锚定到具体的 CHANGELOG 文本、__all__声明、AST 签名或运行时警告任何一位后续审计者都能沿同一路径重新验证。【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考