Warp 特性调研协议：在发布说明撰写中落实源码级事实核查的方法论

Warp 特性调研协议在发布说明撰写中落实源码级事实核查的方法论【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本文解析 NVIDIA Warp 仓库中面向发布说明撰写者的特性调研协议feature-investigation.md它规定了在撰写 release notes 之前如何逐项定位实现、核实符号、暴露限制、识别制品并链接示例。读者将掌握一套可直接复用的六步调研流程以及将其应用于 Warp 源码树warp/_src/、warp/native/、warp/examples/、warp/tests/的具体命令与判定标准从而避免发布说明中常见的功能已上线但限制被埋没引用了不存在的公开符号跨语言示例缺消费端三类评审失败。为什么发布说明需要一份调研协议Warp 的发布说明撰写流程见 SKILL.md将特性发布feature release与缺陷修复发布bugfix release区分对待只有特性发布会执行 Phase 4 的实现调研并强制读取 feature-investigation.md、style-rules.md 与 feature-release-template.md 三份参考文档。协议开篇点明了它的存在理由跳过调研发布说明就会停留在加了什么what was added而丢失它到底能做什么、什么还不能用、在哪里能看到它跑起来what does it actually do, what doesnt work yet, and where can I see it running。历史评审反复暴露同一类缺口协议就是为了在第一遍起草时就把它们抓出来。协议对每个计划写入的 feature 或符号按顺序走完六个 pass定位实现、核实符号引用、暴露限制、识别隐形制品、寻找树内示例、按文档决定限制篇幅。Pass 1把符号解析到真实源码撰写任何描述前先把命名符号解析到 head ref 上的实际文件。协议给出了四类查找路径Python 作用域 APIwp.X、wp.X.Y沿 warp/init.py 的 re-export 链追踪到warp/_src/下的真实模块用git show head-ref:path读取。内核作用域 builtin在 warp/_src/builtins.py 中搜索add_builtin(name, ...)注册。例如tile_dot在 warp/_src/builtins.py 处以tile_dot_value_func的形式实现了参数校验注册后即可在wp.kernel内调用。C/原生代码位于warp/native/下如 warp/native/apic.cu、warp/native/mesh.cu。示例与测试在warp/examples/**、warp/tests/**下按 glob 查找。关键原则CHANGELOG 条目描述的是意图源码描述的才是契约。阅读实现后任何从文档中搬来的措辞都要以源码为准重新校验。Pass 1.5核实每一个符号引用在引用 docstring、CHANGELOG 或设计文档中的 Equivalent toSee alsoUse instead 等交叉引用之前必须确认被引用的符号真实存在且从用户预期的入口可达。对每个计划写入的wp.symbol用两条已经允许的 shell 命令交叉验证# 1) 是内核内置函数能在 wp.kernel 内调用 git show head-ref:warp/_src/builtins.py | grep -nE add_builtin\(\s*symbol # 2) 是模块 re-export能以 warp.symbol 在 Python 作用域访问 git show head-ref:warp/__init__.py | grep -nE \bsymbol\b第一条命中说明该符号可在wp.kernel内调用第二条命中说明它同时以warp.symbol暴露在 Python 作用域。协议给出了这类检查能拦截的典型失败早期wp.tile_dot的 docstring 引用了wp.tensordot作为等价形式但wp.tensordot从未注册为 Python builtin只有 warp/native/quat.h 中的 C 模板tensordot供内部使用对应np.tensordot()全轴收缩语义。若把 docstring 原文直接搬进发布说明就等于凭空发明了一个公开符号。docstring 后来已修正但同类不匹配仍可能在今天存在本 pass 的目的就是抓住它们。对于实现层面的论断使用 fp32 round-trip使用原生 intrinsics跳过运行时检查在实现文件中 grep__CUDA_ARCH__门控。同一操作在不同架构上往往派发到不同代码路径sm_90用原生 PTXsm_80-sm_89用 intrinsic 模拟更老架构和 CPU 用 fp32 round-trip。同时检查成员运算符重载struct/class 内部定义与独立重载文件作用域定义两者可能派发到不同路径从一种运算符形式得出的论断不一定对另一种成立。对于现在支持 N-D / 多维类能力论断先查旧形式已支持什么。现在支持 N 2 的 N-D往往只是抬高了秩上限而不是新增能力。用户侧表述随之不同现在可以对 rank-3 的 tile 操作与省掉了你过去必须手写的批处理循环是两回事。跳过本 pass 的代价发布说明会写出即使 source-of-truth 文档如此记载、但代码交付时并不成立的论断。Pass 2把限制从实现里挖出来功能上线但限制被埋没是过去发布评审最大的缺口。撰写章节之前在实现文件与相邻文件中 grep 已知模式not yet supported、not supported、unsupported、TODO、FIXME、XXXexperimental、unstable、subject to changerequires、must be、currently only、assumes明确抛出限制的异常raise NotImplementedError、raise ValueError(... not supported)同目录下的 README 与 docstring 中的Notes:/Limitations:段落对每个与用户可见表面相关的命中问一个问题用户是否只有等代码跑挂了才会发现这个限制如果是就必须在发布说明中写明可以放在特性描述后的 prose 里或作为 Known limitations 子条目。协议给出的历史案例都是过去发布时未及时暴露的限制.wrpgraph captureVolume 与 BVH 序列化尚不支持只有wp.Mesh通过wp.handle处理 remap。.wrpgraph captureCPU 端加载.wrp仍要求一个 CUDA 构建的 Warp 库。.wrpgraph capture保存的 CUBIN 固定绑定单一 compute capability。cuBQLBVH 后端只支持mesh_query_raypoint/AABB/winding 查询未实现。Pass 3找出明显文件之外的制品对产生新磁盘制品、线格式或跨进程边界的特性不能只看头条文件要读 save / write / serialize 代码并回答三组问题伴生文件或目录写name.wrp是否同时创建name_modules/目录、.meta文件或锁文件分发制品的用户需要知道该带走什么。以本仓库的 APIC 序列化实现为例warp/native/apic.h 的注释明确区分了三条消费路径wp_apic_state_save()写出.wrp文件、wp_apic_cpu_replay_state()执行实时 CPU capture、wp_apic_cpu_replay_graph()/wp_apic_get_cuda_graph()执行已加载的.wrp图CPU/CUDAPython 侧在 warp/_src/apic/capture.py 的capture_save()中先把内存区域、内核与 mesh 注册进 C 状态再写.wrp。架构或版本绑定制品是否绑定单一 compute capability、单一 Warp 版本、单一 Python 版本如果是必须说明。反向依赖加载需要什么而保存不需要CUDA contextwp_init的调用顺序特定的构建风味这些内容在章节中以简短的 What gets written 段落或字面目录树代码块呈现不要让读者自己推断。这正是 feature-release-template.md 中LEAD_FEATURE_ARTIFACT_BLOCK_IF_ANY占位符的设计用途。Pass 4在树内找到可链接的示例对每个 lead feature 和每个描述实质性能力的### …块在仓库里搜索可用的示例。历史评审曾点名批评你为这个功能发了真实的 C 示例却只字不提# 跨语言特性从 Python 使用 C git ls-tree -r --name-only head-ref -- warp/examples/cpp/ | grep -i feature-keyword # Python 示例kernel、demo git ls-tree -r --name-only head-ref -- warp/examples/ | grep -i feature-keyword # 测试作为用法参考 git ls-tree -r --name-only head-ref -- warp/tests/ | grep -i feature-keyword例如本仓库 warp/examples/cpp/ 下就有02_apic_visualization与03_apic_visualization_cpu两个 APIC 相关示例与协议反复引用的 graph capture 序列化场景直接对应可作为该特性章节的树内链接候选。链接规则严格用发布 tag 的 URLvversion相对路径链接示例绝不按 SHA 链接绝不按main链接文件可能移动要链接的 tag 必须是发布时会真实存在的。若没有匹配示例但特性随发布携带了参考应用跨语言特性常见要显著列出它们。用户阅读发布说明时绝不应该还需要自己去 grep 仓库才能找到可运行的起点。Pass 5跨语言特性的双侧示例任何跨越语言边界的特性Python → C、Python → JAX、Python → 独立运行时都需要两侧各一段代码示例而不只是 Python 一侧。从 C 暴露却只给一个 Python 片段、零 C 片段是评审必挂的模式。当特性跨界时展示 Python 编写侧一段可工作的片段。展示消费侧片段C 头文件与函数调用JAX 的jax_kernel绑定等有树内示例就从示例中提炼。明确点名消费侧头文件或 import 路径。说明消费侧的运行时前提CUDA context、JAX 0.8、是否需要 Python 解释器。以 APIC 为例warp/native/apic.h 声明了完整的 DLL 导出 C APIwp_apic_load_graph(context, path, device_type)支持在无 Python 环境下加载.wrp图device_type取APIC_DEVICE_CUDA0或APIC_DEVICE_CPU1wp_apic_set_param/wp_apic_get_param读写参数wp_apic_launch(graph, stream)在指定流上执行wp_apic_get_cuda_graph/wp_apic_get_cuda_graph_exec取出底层 CUDA 图句柄wp_apic_register_loaded_cpu_kernel在加载.o模块后完成 CPU kernel 符号注册。消费侧示例必须省略样板时的三条纪律完整消费侧示例有时太长无法内嵌50 行以上遍历模块目录、加载目标文件、注册 kernel 符号、建立 CUDA context。此时必须全部做到逐条核对 API 调用签名与对应头文件一致。在warp/native/feature.h中 grep 片段里出现的每个函数wp_apic_load_graph、wp_apic_set_param等确认参数列表与类型和片段展示的一致。发布说明里的代码是大多数读者接触该 API 的唯一途径签名漂移会让复制粘贴静默失败。在正文中显式声明省略。不要让读者误以为片段原样可运行。示例完整示例还会遍历_modules/目录逐个用wp_load_obj加载.o解析 kernel 符号并在首次重放前用wp_apic_register_loaded_cpu_kernel注册。下面片段省略了这些样板。在被省略步骤的位置加行内占位注释让只扫代码块的读者也能看到缺口// (遍历 demo_modules/加载每个 .o注册 kernel。见链接示例。)用发布 tag URL 链接完整树内示例[example-path](https://github.com/NVIDIA/warp/blob/vversion/path)。绝不按main链接绝不按 SHA。绝不静默省略。复制粘贴片段的读者必须知道他们拿到的是 API 形状草图而不是可运行程序。Pass 6按文档成熟度决定限制篇幅对每个描述实验特性或存在显著缺口的功能块决定限制信息放哪里检查关联的 Sphinx 文档是否已全面枚举限制。查看docs/user_guide/*.rst与docs/api_reference/*.rst中该特性对应的页面搜索 Current limitationsKnown limitationsCaveatsNotes: 等标题/提示块。若文档已全面枚举内联总结 1-2 条用户首次使用就会撞上的关键限制并链接到文档章节获取完整列表。避免重复维护一份长枚举造成发布说明草稿与下次文档更新之间两个事实来源漂移。若文档未清晰枚举在发布说明中内联枚举全部限制组织为**Known limitations:**下的带标签列表。跳过实验特性的限制说明是评审失败模式读者只会在代码崩了之后才发现限制。但把文档已有的全面枚举复制进发布说明同样是问题既让章节臃肿又制造双份事实来源。红线清单What not to do协议结尾给出四条硬性红线不要发明限制。源码没有显示的就不要编造。不要伪造伴生文件。save只写一个文件就不要声称两个。不要链接没打开过的示例。链接解析不了就删掉。不要改写 docstring 的 Notes 导致自相矛盾。拿不准就引用原文。与发布说明技能体系的关系本协议不是孤立文档它是 Warp 发布说明技能SKILL.md的强制组成部分。撰写特性发布说明时Phase 4 要求把本协议应用到 lead feature 及每个计划写入的### …块产出的调研结果直接决定feature-release-template.md 中 lead feature 是否标注实验性 admonition、是否带 Key capabilities 与 Known limitations 条目、是否带制品目录树、是否带消费侧代码块style-rules.md 中代码示例默认化、GFM admonition 规范、输出渲染规范、交叉语言示例规范的落实最终发布说明让读者能开始用这个功能而非看起来像发布公告。协议的核心信息可以压缩为一句话发布说明的每个论断都必须能在当前仓库的源码、配置或测试中找到落点找不到落点的论断要么补齐证据要么删掉。延伸阅读特性调研的两份配套参考style-rules.md、feature-release-template.md与完整的发布说明六阶段流程SKILL.mdWarp 的变更记录以 Towncrier fragment 形式维护在 changelog片段命名与分类规则见 changelog/README.md。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考