Warp 发布审计报告模板详解report-template.md 的结构、占位符契约与渲染规则【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warpWarpNVIDIA 的 GPU 加速仿真、机器人与机器学习 Python 框架在每次正式发版前后会用warp-release-audit这个 Claude Code Skill 生成一份 Markdown 审计报告供发布负责人做 keep/defer 决策。本文以 report-template.md 为主体逐节拆解这份报告的骨架头部元信息、bake 分布、New API / Breaking / Changes / Fixed 各章节的占位符契约以及条件附录的三种渲染形态并结合 SKILL.md、render-rules.md 与配套脚本说明每个区块的数据从何而来、按什么规则填进模板。一、模板在发布审计流程中的定位warp-release-audit技能的工作流程定义在 SKILL.md 中共 6 个阶段报告模板在Phase 6b被加载Phase 1 对齐范围从 VERSION.md 读取版本串当前为1.18.0.dev3并与 warp/config.py 中声明的版本做交叉校验解析出上一 minor 的 tag 作为 base探测upstream/release-target是否存在以确定 head 与报告模式版本串含rc为Release Candidate模式含dev为Pre-Release模式。Phase 2 采集事实运行 scripts/list_commits.py 生成base..head的提交清单 JSON从head-ref而非工作区枚举 changelog/ 下的 Towncrier 片段并用固定版本towncrier25.8.0在临时 detached worktree 里渲染--draft得到待定发布条目视图同时读取 docs/user_guide/compatibility.rst 与 design/deprecations.md 作为稳定性边界与弃用计划的权威来源。Phase 3 交叉引用把渲染出的 changelog 条目与提交按 GH ref / 片段来源做 join无提交背书的片段进入附录。Phase 4 API 面分析判定哪些Added条目是真正新增的 API、提取签名与 docstring、计算 base 与 HEAD 的签名 diff、检查弃用兼容路径与语义级破坏。Phase 5 语言审查与 bake 聚合按 language-review-examples.md 给条目打标记并按提交在 main 上的浸泡时间聚合 bake 分布。Phase 6 写报告6a 撰写定性 highlights6b 读取模板与 render-rules.md 填充所有{{PLACEHOLDER}}6c 按 destination-rules.md 写入 secret gist默认文件名固定为warp-version-string-prerelease|rc-report.md同版本多次运行原地修订同一 gist或本地 markdown 文件回退方案。模板文件本身只做两件事定义报告的章节骨架以及用 HTML 注释给出每个占位符的填充契约。模板内所有{{...}}都必须被替换不允许原样残留。二、报告头部版本、模式、引用与头部计数模板的前 20 行report-template.md构成报告头部# Warp {{VERSION_STRING}} {{REPORT_KIND}} Report Generated: {{REPORT_DATE}} - Mode: {{MODE_DESCRIPTION}} - Head: {{HEAD_REF}} {{HEAD_SHA_SHORT}} - Base: {{BASE_REF}} {{BASE_SHA_SHORT}} - Commits in range: {{N_COMMITS}}各占位符的填充契约如下占位符含义填充规则{{VERSION_STRING}}原始版本串原样保留如1.13.0dev0或1.13.0rc1{{REPORT_KIND}}报告类型Pre-Release或Release Candidate在 Phase 1 由版本串与 head ref 共同确定{{MODE_DESCRIPTION}}一句话模式说明预发布固定为 Pre-release audit of unreleased work on mainRC 固定为 Release candidate readiness review (release branch cut){{HEAD_REF}}/{{HEAD_SHA_SHORT}}审计上界head 通常为upstream/release-targetRC 模式或upstream/main预发布模式需记录使用了哪个 fallback{{BASE_REF}}/{{BASE_SHA_SHORT}}审计下界上一 minor 系列的最高 tagmajor 边界回退到上一 major 的最高 tag{{N_COMMITS}}区间提交数来自list_commits.py的commits数组长度紧接着是Headline counts区块模板 L23-L29- {{N_NEW_API}} new public APIs (Python: {{N_NEW_PY}}, kernel: {{N_NEW_KERNEL}}) - {{N_BREAKING}} breaking changes - {{N_CHANGED}} changes to existing API - {{N_BEHAVIORAL}} behavioral / support changes - {{N_FIXED}} fixes这里承载报告的定量摘要。与之配套的定性摘要是后文的 Release highlights二者分工明确计数块放数字highlights 放判断。模板注释特别强调 highlights 中不得重复计数Do NOT include counts因为读者刚在头部看到过。三、Bake 分布表与 main 烘焙异常横幅模板 L31-L37 是 bake 分布表衡量提交在 main 分支上跑了多久才进入本次发布| Bucket | Commits | |---|---:| | 14 days in main | {{N_BAKE_GREEN}} | | 7 to 14 days | {{N_BAKE_YELLOW}} | | 7 days | {{N_BAKE_ORANGE}} |阈值14 / 7-14 / 7 天是固定的三档对应已充分浸泡 / 中等 / 风险偏高。{{ANOMALY_BANNER_IF_ANY}}L39的触发契约是整个模板中条件最精细的部分模板内注释L41-L60规定横幅只在至少一个提交满足main_match_state missing时触发提交主题在main_ref上不存在格式为 ⚠️ **N commits in the release have no equivalent on main. Investigate: these shipped without nightly/main-branch bake.**这些提交绕过了 main 分支的 nightly 验证是真正的 bake 缺口信号。ambiguous主题在 main 上出现多次如 revert 或重放提交不算缺口提交确实在 main 上只是脚本无法选出唯一规范出现位置。它们以独立行⚪ ambiguous main match: K commits出现在 bake 表中不触发横幅。预发布模式下head 即 main横幅永不触发bake 表被替换为基于days_since_merge的 Age distribution 表——head 就是 main 时不存在没在 main 上跑的概念。若resolved.empty_main_index truebase..main_ref区间内 main 无提交则用醒目的头部说明如 main_ref had no commits inbase..main_ref; main bake unverifiable替代常规横幅避免误报。底层支撑来自 list_commits.py脚本为每个提交输出main_match_stateunique/missing/ambiguous与days_in_main、days_since_merge字段见 build_commit_entry。missing与ambiguous两种状态下days_in_main均为null模板契约因此禁止拿null去比三档数值阈值脚本对main_ref区间为空的情形也会主动告警main 函数内的empty_main_index分支。四、Release highlights 与目录TOCRelease highlights模板 L63-L67{{HEADLINE_SUMMARY}}是整份报告中唯一依赖定性判断、而非机械渲染的区块。模板注释L69-L93给出了严格写作契约2-3 句引言段 4-8 条要点少于 4 条通常意味着漏了主题多于 8 条说明在罗列变更而非提炼亮点每条以加粗的 2-6 词标题开头冒号后接一句话说明它是什么、为什么重要适用时内联风险标记 N days bake该亮点最小浸泡不足 7 天、Experimental仅当实验能力本身值得进头条时、⚠️ Breaking亮点本身是破坏性变更通用条目形状为- **capability headline** (GH-NNN): 用户现在能做什么、为何重要破坏性条目写作- **⚠️ Breaking: behavior headline** (GH-NNN): 受影响用户与具体迁移。SKILL.md 的 Phase 6a 还补充了取舍规则纯一行可述的 bugfix、纯 CI/构建变更、已隔离的内部重构、用户无感的参数默认值调整一律不进 highlights每条要点以解锁的能力开头而不是机制且所有 GH ref 必须渲染为 issue 超链接、禁止(multiple GHs)之类缩写。Contents模板 L96-L128{{CONTENTS_BULLETS}}要求把正文每个###级标题不仅是##都展开为目录子项New API 下按 Python/Kernel 两个 scope 再列出每个符号Breaking / Changes 按条目标题列子项。模板给出示例形状并注明示例符号名只是占位示意不得照抄交付。模板注释还解释GitHub 会渲染浮动大纲面板但显式 TOC 对纯文本读者仍有价值。五、New APIPython 与 Kernel 双 scope 的表格和符号级明细模板 L132-L173 定义 New API 章节结构为汇总表格 逐符号明细块汇总表格按 Kind 分组{{NEW_PYTHON_TABLES_BY_KIND}}L136。每个 Kind 一张表如 Functions、Classes / context managers、Scalar types、Decorators、Enums / flags列固定为Symbol | Description | GH | Bake。Symbol 单元格使用短形调用形状带参数名与默认值、但不带类型标注枚举、标量类型、装饰器不加括号。逐符号明细块{{NEW_PYTHON_DETAIL_BLOCKS}}L146契约形状为### wp.symbol Links: GH-NNN, commit(s): sha Source: public source path Bake: bucket and days python signature-shaped declaration verbatim docstring, when present契约细节类要给出类 docstring、构造函数和**每个**额外公共方法枚举与 flags 要列全每个成员及其文档内核内建kernel builtin不得展示 add_builtin(...) 注册调用而要从其参数**合成**一个 Python 风格的公开签名内建名做函数名input_types/inputs 各项做带类型标注的参数value_type/output 做返回标注docstring 取注册调用的 doc 参数原文。 3. **Kernel scope**{{NEW_KERNEL_TABLES_BY_KIND}} / {{NEW_KERNEL_DETAIL_BLOCKS}}L168-L173沿用同一分组规则典型 Kind 为 Tile operations、Queries、Types、Primitives。 这些明细块的数据并非手抄SKILL.md Phase 4b 规定对 Python 符号用 ast.parse 定位 FunctionDef/ClassDef、重新字符串化参数保留类型标注、用 ast.get_docstring(node) 原样提取 docstring内核内建则读 HEAD 上的 [warp/_src/builtins.py](https://link.gitcode.com/i/c335355c814751cf4d9c0cc5e860db63) 找到 add_builtin(name, ...) 调用后合成签名。符号解析失败时Phase 4c渲染带 ⚠️ 说明的条目禁止编造 wp.*(no symbol) 这类桩头。 ## 六、Breaking Changes扁平列表与准入门槛 模板 L175-L200{{BREAKING_ENTRIES}}规定该章节是**扁平列表**不按识别方式设子标题且只收录对受支持、可触达表面的惊动性变更。准入/分流规则模板注释 L181-L184与 [classification-rules.md](https://link.gitcode.com/i/0fd3e7ff732c47b27eb321697ecb56d9) 的 Surface/Reachability/Deprecation/Action 记录一一对应 - **满足弃用窗口的计划移除**与**实验性变更**不算惊动性 breaking归入 Changes to Existing API使用更温和的标签Planned removal / Experimental - 每条条目的渲染格式### 符号名或短描述标题标题用冒号分隔不用破折号随后是 Links: GH-NNN, commit(s): sha. N days baked in main.视情况附 diff 代码块签名变化时或自包含的 before/after 示例行为变化时优先取自现有测试或文档否则用已验证的复现及其输出再跟 1-3 句面向用户的解释文字若条目源自 CHANGELOG 则原文引用整段。 SKILL.md Phase 4g 进一步规定每个 Breaking Changes 条目必须有五类证据之一——CHANGELOG 显式 **Breaking:** 标注、签名 diff 检测到的形状变化、公共 stub 移除、弃用兼容路径新增异常Phase 4f或**助手实际运行 base 与 HEAD 两版构建并比对输出**的语义级验证。Never punt with please verify模棱两可的候选要么跑代码验证、要么丢弃未验证的标记不得进入报告。 ## 七、Changes to Existing API汇总表与条目契约 该章节模板 L202-L238覆盖 CHANGELOG 的 Changed / Removed / Deprecated 三类条目外加从 New API 分类阶段分流过来的能力扩展例如Add support for X in existing Y。 **汇总表格**{{CHANGED_SUMMARY_TABLE}}列为API | Kind | Breaking | Description | GH | Commits | Bake。其中 Kind 取值为 signature change、new parameter、capability extension、removed、deprecated、semantic changeDescription 是不超过 10 个词的短语Breaking 取值 Yes、No、Planned removal 或 Experimental。 **逐条明细块**{{CHANGED_DETAIL_BLOCKS}}契约 text ### wp.symbol: change kind Breaking: **Yes | No | Planned removal | Experimental** (short reason) Links: GH-NNN, commit(s): sha Bake: bucket and days Deprecation window: when applicable diff - base signature when applicable HEAD signature when applicableFrom CHANGELOG要点标题用冒号而非破折号签名形状变化用围栏 diff 块展示 base 与 HEAD 两行纯语义变化则跳过 diff 块改为给出提交链接与完整 CHANGELOG 文本移除类条目只保留 - 行、省略 行移除条目必须附弃用窗口在 [CHANGELOG.md](https://link.gitcode.com/i/69c9127b8af9622a43268962d74fc77f) 中自 Towncrier 插入标记向下扫描同名符号或同 GH ref 的最早 Deprecated 条目写成 Deprecated in X.Y.Z; removed here.找不到先验条目则**不得编造版本**实验性条目要注明引入实验标记的发布版本。 ## 八、Behavioral Support Changes 与 Fixed **Behavioral Support Changes**模板 L240-L250{{BEHAVIORAL_SECTIONS}}不逐条罗列而是**按主题分组**由条目内容综合出简短描述性小标题如 Anisotropic voxel spacing、CPU compile performance、Build requirements相关主题放在一起每个主题配一段短摘要、链接、提交与 bake。render-rules 同时规定标题需要分隔时同样用冒号。 **Fixed**模板 L252-L261{{FIXED_TABLE}}只有一张表列为 Fix | GH | Commits | Bake。两条硬规则Fix 列保留 CHANGELOG 全文、**禁止截断**不得提及已发布补丁版本中修复的 bug——提交清单工具的作用域本来就是 base..head那些内容已被天然排除报告不得主动制造对比这与 [render-rules.md](https://link.gitcode.com/i/134ff9ab8ee5ee9923fdeffc98a62a36#L28-L28) 第 3 条呼应。 ## 九、条件附录Changelog Review Notes 的三种渲染形态 模板末尾L263-L317{{OPTIONAL_APPENDIX}}是最长的条件渲染契约依据两个输入——无匹配提交的 changelog 片段列表与语言审查标记列表——分三种情况 1. **两者皆空**什么都不渲染无附录标题、无尾部章节 2. **恰好一个非空**不用 Audit Appendix 伞形标题直接把该节渲染为顶级章节如 ## Changelog Fragments Without Matching Commits表体包在 GFM details 块里默认折叠 3. **两者皆非空**渲染伞形章节 ## Audit Appendix每个子节各带一个 details。 两张表的结构分别是 | 表 | 列 | |---|---| | 无匹配提交的片段 | Source fragments | Entry | GH refs | Suspected reason | | 语言审查标记 | Source fragments | Entry | Flag | Why | 列规则源片段路径与完整条目文本一律不截断语言标记符号为 疑似 GH ref 错误、️内部实现语言泄漏、过于简短或缺上下文一条条目命中多个标记时**每个标记一行**。标记的判定标准来自 [language-review-examples.md](https://link.gitcode.com/i/829f0758f8753811e4b6936cc64d067b) 分两级级一纯本地核对 GH ref 关联提交的 subject 与文件路径是否与条目主题相符如条目讲 kernel API 而提交只碰 CI 文件即标记级二需要 gh CLI 已认证时比对 issue 标题️ 针对 warp._src.* 内部路径、C/CUDA 内部类型如 launch_bounds_t、下划线私有标识符 针对约 10 词以下且无上下文的条目。其哲学是提出来但不拦截标记只为给人工复核提问题不自动改写任何片段也不修改生成产物 [CHANGELOG.md](https://link.gitcode.com/i/69c9127b8af9622a43268962d74fc77f)宁可误报不可漏报。 模板最后两行注释L316-L317是收尾纪律报告到此结束——禁止追加 end of report、收尾引语、致谢或任何终结标记最后一节就是最后一节。 ## 十、渲染层硬约束与 render-rules.md 配套生效 Phase 6b 填模板时必须同时遵守 [render-rules.md](https://link.gitcode.com/i/134ff9ab8ee5ee9923fdeffc98a62a36) 的全部规则这里汇总最影响版面的几条 - **URL 形状固定**提交链接为完整 commit URL含完整 SHAissue 链接为完整 issue URL - **全文禁止破折号em dash**标题、要点、表格单元格一律改用冒号、括号或改写句子 - **禁止出现技能内部术语**读者不知道 Phase 4f、tier-1 heuristic 指什么需要解释时改用面向用户的白话 - **每个 GH ref 必须是 markdown 超链接**表格单元、标题、正文、CHANGELOG 引用块中出现的 GH-NNNN 一律链接化一行六个 ref 就渲染六个链接禁止纯文本 (GH-1287, GH-1298, ...) - **签名与 docstring 合并在同一个 python 围栏代码块中**函数/类/枚举/内核内建各有固定形状类要列出全部公共方法枚举要列出全部成员及整数值内核内建用合成签名而非注册调用且禁止拆成 Signature 与 Docstring 两个小节、禁止逐行引用 docstring - **API 表格列序与短形签名约定**如第五、七节所述 - **附录伞形标题仅双非空时使用** - **禁止 Phase 名出现在输出中**。 ## 十一、占位符全景速查 | 占位符 | 所在章节 | 数据来源 | |---|---|---| | {{VERSION_STRING}} {{REPORT_KIND}} {{REPORT_DATE}} {{MODE_DESCRIPTION}} {{HEAD_REF}} {{HEAD_SHA_SHORT}} {{BASE_REF}} {{BASE_SHA_SHORT}} {{N_COMMITS}} | 报告头部 | Phase 1 解析 [VERSION.md](https://link.gitcode.com/i/1664e3497c19693d6046f8553f9b21cc) 与 warp/config.py、git tag/rev-parse提交数来自 [list_commits.py](https://link.gitcode.com/i/dc091afc2591a7b7d71d5f84c8c4bc73) | | {{N_NEW_API}} {{N_NEW_PY}} {{N_NEW_KERNEL}} {{N_BREAKING}} {{N_CHANGED}} {{N_BEHAVIORAL}} {{N_FIXED}} | Headline counts | Phase 4 分类结果 | | {{N_BAKE_GREEN}} {{N_BAKE_YELLOW}} {{N_BAKE_ORANGE}} | Bake distribution | days_in_main 三档聚合null 不参与比较 | | {{ANOMALY_BANNER_IF_ANY}} | 头部横幅 | 是否存在 main_match_state missing 的提交 | | {{HEADLINE_SUMMARY}} | Release highlights | Phase 6a 定性撰写 | | {{CONTENTS_BULLETS}} | Contents | 正文全部 ##/### 标题 | | {{NEW_PYTHON_TABLES_BY_KIND}} {{NEW_PYTHON_DETAIL_BLOCKS}} {{NEW_KERNEL_TABLES_BY_KIND}} {{NEW_KERNEL_DETAIL_BLOCKS}} | New API | Phase 4a/4b 的 base/HEAD 符号解析与签名提取 | | {{BREAKING_ENTRIES}} | Breaking Changes | Phase 4d-4g 的五类证据 | | {{CHANGED_SUMMARY_TABLE}} {{CHANGED_DETAIL_BLOCKS}} | Changes to Existing API | Phase 4a/4d 的签名 diff 与弃用窗口查询 | | {{BEHAVIORAL_SECTIONS}} | Behavioral Support | 主题分组综合 | | {{FIXED_TABLE}} | Fixed | CHANGELOG Fixed 条目全文 | | {{OPTIONAL_APPENDIX}} | 条件附录 | Phase 3 的无提交片段 Phase 5a 的语言标记 | ## 十二、配套工具与失败模式 模板渲染只是流水线的末端其可信度依赖上游工具链 - [list_commits.py](https://link.gitcode.com/i/dc091afc2591a7b7d71d5f84c8c4bc73)确定性、纯标准库枚举 base..head 提交跳过 merge提取 \bGH-(\d) 形态的 issue 引用通过 subject 精确匹配定位 main 侧等价提交并输出三种 main_match_state对歧义 ref 直接报错退出[rev-parse](https://link.gitcode.com/i/dc091afc2591a7b7d71d5f84c8c4bc73#L179-L193) 把任何 stderr 都视为硬错误拒绝输出负的 days_since_merge。 - [diff_public_api.py](https://link.gitcode.com/i/4a88a047e6ee8c48305e95a644c72610)独立于 CHANGELOG 内容对比 base 与 HEAD 提交的公共 API含 .pyi 公共 stub 的移除以 JSON 输出供 Phase 4e 消费模块选择与破坏性签名形状信号/通常非破坏信号的判定细则见 [classification-rules.md](https://link.gitcode.com/i/0fd3e7ff732c47b27eb321697ecb56d9)。 - Towncrier 片段渲染固定 towncrier25.8.0、--draft 模式、临时 worktree 用完即删与 [changelog/README.md](https://link.gitcode.com/i/813df8f434933052ab80e7a209b57ab4) 中的片段规范六类后缀 added/removed/deprecated/changed/fixed/documentation、issue 数字或 slug 孤儿标识符、.1 计数器及 [design/towncrier-changelog-fragments.md](https://link.gitcode.com/i/42ed09327840498c0bdd87f99e3e6d41) 的设计文档保持一致。 SKILL.md 末尾的 Failure modes 一节定义了渲染异常时的行为片段查无提交背书时进附录并注明 no associated commit found, verifyAdded 条目符号在 HEAD 无法解析时渲染 ⚠️ 提示而非桩名upstream/ 远端缺失时替换为 origin/ 并在头部注明head 与 main 无差异时视为 headmain 跳过 cherry-pick 检测无待定片段时渲染空 draft 并告警**绝不**拿最近的历史发布段顶替Towncrier draft 失败则原样输出命令错误并停止不得用手写近似值冒充发布段落。 综合来看这份模板的价值在于把发版前该确认什么固化成了可机械执行的契约头部五组计数回答范围多大bake 分布与横幅回答风险有多新鲜四个正文章节回答具体变了什么、证据是什么条件附录回答changelog 本身还有哪些疑点。配合固定版本的 Towncrier、确定性的提交清单脚本与签名 diff 工具报告的可复现性与可审计性完全由仓库状态决定这也是 Warp 以fragment 驱动 审计模板管理发版沟通的核心机制。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考