Warp 变更日志影响排序准则Towncrier 条目按用户影响分层的排序方法【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本文以 Warp 仓库中warp-changelog-audit技能的核心参考文档《Impact Sorting Rubric》为主体完整解读其三档用户影响分级标准、同档内的平局裁决规则以及一份完整的 Before/After 排序实例并结合 pyproject.toml 中的 Towncrier 配置与 CHANGELOG.md 真实发布记录说明这套排序准则在 Warp 发版流水线中的定位、适用前提与可验证依据。读完后你将掌握在生成发布章节内对 changelog 条目做高影响优先、主题聚簇为辅的排序方法并能理解其背后的工具链约束。排序准则在 Warp 发版流程中的位置Warp 使用 Towncrier 目录提交小型 fragment 文件如1708.fixed.md、fix-cuda-graph-capture.fixed.md发布时再统一渲染。fragment 的命名、类别与内容规则以 changelog/README.md 为准。排序准则文件 sorting-rubric.md 的头部说明了它的加载时机与职责Loaded by Phase 4. Use these criteria to score each CHANGELOG entrys user-impact when sorting within a subsection. Sort high → mid → low; within a tier, prefer topic clustering as a soft tie-breaker.它服务于 SKILL.md 定义的审计流程Phase 5 完成 fragment 的语言规范化后在 release 分支的 Phase 6 中执行最终 Towncrier 构建此时生成器输出的## [X.Y.Z]章节条目是按 issue 编号的默认顺序排列的——因为 Towncrier 不做语义排序。这正是排序准则的用武之地在生成的每个子小节Added/Removed/Deprecated/Changed/Fixed/Documentation内部按用户影响从高到低重排并同步更新比较链接块。SKILL.md 的硬性规则也印证了这一边界After the final build, edit only the new generated release section and the comparison-link block. This release-only normalization is where impact sorting and line wrapping happen.也就是说影响排序只发生在发布分支的最终规范化阶段不得回改CHANGELOG.md中的历史章节也不得用 Towncrier 的默认顺序重建已打 tag 的版本章节。前置约束Towncrier 配置决定了条目形态排序准则中大量判据**Breaking:**标记、### Removed小节、**Experimental**头部特性等之所以能成立依赖两个仓库事实Towncrier 渲染配置pyproject.toml 第 230–268 行的[tool.towncrier]段directory changelog、filename CHANGELOG.md、start_string !-- towncrier release notes start --\n即渲染锚点title_format ## [{version}] - {project_date}对应 SKILL.md 解析规则中的发布头正则issue_format [GH-{issue}](https://github.com/NVIDIA/warp/issues/{issue})所以 fragment 文件名中的数字会被自动追加为 issue 链接条目正文内不应手写该链接——这与 sorting-rubric.md 工作示例中每条末尾的[GH-xxxx]标注一致wrap false即 Towncrier 生成时不折行120 列折行由 Phase 6 的规范化步骤人工完成六个类别added / removed / deprecated / changed / fixed / documentation各自映射为### Added等子小节showcontent true。稳定性标记由 fragment 正文承载。**Breaking:**与**Experimental**:前缀是 fragment 内容的字面标记SKILL.md 的解析规则将其定义为字面量检测标记规范本身由 language-conventions.md 约束。**Experimental**标记弱化的是稳定性契约而不是重要性——这是排序准则中一个关键判断带该标记的重大实验特性仍然应排在子小节顶部。真实案例可参见 CHANGELOG.md 中 1.17.0 版本### Added小节开头的**Experimental**: Add APIs for compiling Warp modules for external C and CUDA consumers...条目。三档用户影响标准sorting-rubric.md 将每个条目归入 High / Mid / Low 三档。以下完整继承原文档标准并逐条补充仓库佐证。High impact子小节顶部解锁此前不可能工作流的全新公共 API新的函数族、类型、类或装饰器。例如wp.tile_dot()引入 tile 点积能力wp.kernel(name...)提供自定义内核命名。新的标量类型、公共协议或平台/语言互操作边界。原文档列举了wp.bfloat16、外部纹理互操作、Python 捕获图形的 C 回放等。当前仓库可确认bfloat16已是一等标量类型warp/init.pyi 中有from warp._src.types import bfloat16 as bfloat16且它进入了DTypeFloat/DTypeScalar类型变量第 273–274 行说明其地位与普通浮点类型一致——这类条目天然高影响。破坏性变更条目含字面**Breaking:**标记。移除条目位于### Removed小节。影响所有用户的默认值变更如默认优化级别、默认 codegen 路径、默认对齐行为。原文档特意说明影响每个用户的默认值变更属于高影响因为所有下游代码都会感受到行为差异。带**Experimental**标记的头条实验特性标记弱化的是稳定性契约但一个重大实验特性仍然属于顶部条目。平台 / Python / 依赖支持变更如弃用 Python 3.9、提高 CUDA Toolkit 最低版本。原文档的解释很关键——这些是高影响的因为它们可能让用户根本无法升级即阻塞性比改动幅度更重要。Mid impact已有 API 上新增参数或选项原文档给出三个例子——Cholesky 的fill_mode、tile_load的aligned、wp.kernel的module_options字典。这些属于扩展既有面未创造新能力类别。正常使用中用户会遇到的行为的 bug 修复。热路径上有量化声明的性能提升如~4x faster shared memory writes。量化声明是进入 mid 档的门槛之一无量化依据的微调不达标。新的文档页、示例或用户指南章节。原文档同时给出反向边界typo fix 不属于 mid 影响很可能根本不该出现在 CHANGELOG 中引用了 language-conventions.md 的什么不该进 fragment清单。可选默认关闭但需要时有用的新公共工具 / 上下文管理器 / 跟踪设施。Low impact子小节底部正常使用中不太可能触发的边角 case 的 bug 修复。没有用户可感知阈值变化的性能微调。新暴露给高级用户的内部 helper。小的 docstring / 日志信息改进原文档备注这类多数本不该进 CHANGELOG如果混进来了就压到最底部。同档内的平局裁决Tie-breakers同一条目落在同一影响档内时按以下顺序裁决主题聚簇Topic clustering如果同档内存在同一主题的相邻条目例如多条wp.tile_*新增优先选择能让聚簇保持完整的摆放位置。具体性Specificity指名单个符号的条目比泛主题式条目更清脆易读。同档内优先具体、其次主题式。原文档随后给出了一条不可协商的硬约束Topic clustering is a soft rule.Never demote a higher-impact entry to enforce grouping.If the top of a subsection is a tile feature, the second slot is whatever is second-most-impactful, even if it is a fem feature. The cluster picks up wherever the next tile entry naturally falls.即聚簇是软规则绝不为维持聚簇而把高影响条目降级。若子小节首位是 tile 特性第二位放次高影响的条目即可哪怕它是 fem 特性tile 聚簇在其后自然落位的地方再接续。这条规则防止了为了美观牺牲信息优先级的常见失误。完整工作示例Worked Examplesorting-rubric.md 给出了一份按合并时间序Before的### Added小节及其排序后After结果。Before 为时间序### Added - Add wp.tile_query_valid() for tile BVH/mesh AABB query loops [GH-1335]. - Add wp.bfloat16 scalar type with NumPy DLPack Torch JAX interop [GH-1332]. - Add aligned parameter to tile_load() and tile_store() [GH-1236]. - Add wp.tile_dot() for tile dot products [GH-1364]. - Add wp.handle scalar for graph-capture mesh remapping [GH-1349]. - Add module_options dict parameter to wp.kernel [GH-1250].After 为重排结果注释说明每条的档位理由### Added - Add wp.bfloat16 scalar type with NumPy DLPack Torch JAX interop [GH-1332]. # high — new scalar type - Add wp.handle scalar for graph-capture mesh remapping [GH-1349]. # high — new scalar type, clusters with bfloat16 - Add wp.tile_dot() for tile dot products [GH-1364]. # high — new public API, different topic - Add wp.tile_query_valid() for tile BVH/mesh AABB query loops [GH-1335]. # mid — tile cluster - Add aligned parameter to tile_load() and tile_store() [GH-1236]. # mid — tile cluster (extends existing tile API) - Add module_options dict parameter to wp.kernel [GH-1250]. # mid — different topic, lower in tier原文档对示例的解释要点值得逐句拆解两个新标量类型聚在最顶部因为两者都是高影响且同主题new scalar type——wp.bfloat16与wp.handle恰好同属标量类型主题满足 High 档内的主题聚簇。wp.tile_dot是高影响但主题不同所以它保持第三位仍在 high 档内不被降级以维持两个标量条目相邻——这正是Never demote硬约束的示范。两条 tile 条目聚在 mid 档因为它们共享主题tile_query_valid与aligned参数都是 tile 簇而aligned参数扩展既有 tile API所以是 mid 而非 high。module_options收尾主题不同且是 mid 档中影响最低的一条落在子小节末尾。从仓库结构看这些示例符号大多能在当前代码中找到对应物佐证了准则与真实 API 面的贴合bfloat16与handle均自 warp/_src/types.py 导出见 warp/init.py 的from warp._src.types import handle as handletile_dot的公共签名见 warp/init.pyi 的def tile_dot(a: Tile[Any, ...], b: Tile[Any, ...]) - Tile[Any, tuple[Literal[1]]]。排序结果与比较链接的配套更新排序不是孤立动作。按 SKILL.md Phase 6 的流程重排之后还需将生成的章节折行至最多 120 列Towncrier 生成的 issue 链接保持在条目末尾对应issue_format的渲染位置在比较链接块中新增[X.Y.Z]条目并把[Unreleased]轮换为vX.Y.Z...HEAD形式。当前 CHANGELOG.md 末尾即处于该状态[Unreleased]: https://github.com/NVIDIA/warp/compare/v1.17.0...HEAD表明 1.17.0 已发布、下一版本条目仍在累积——这正是排序准则将要作用于的目标场景不编辑任何更旧版本的发布章节若排序发生在发布分支的最终构建中构建、fragment 删除、最终顺序与链接变更应合并在一个专用的 release changelog commit中并记录其完整 SHA供 post-release 同步阶段Phase 2按 tag 权威回写 main 使用。适用前提与限制本准则仅约束单个## [X.Y.Z]章节内、各###子小节内部的条目顺序六个子小节的相对顺序Added → Removed → Deprecated → Changed → Fixed → Documentation由 Towncrier 的类别定义固定不在重排范围内。判据中的标记检测**Breaking:**、**Experimental**、### Removed归属依赖 fragment 书写规范该规范由 changelog/README.md 与 language-conventions.md 共同约束若 fragment 本身违反规范如手写 issue 链接、非祈使句应先修复再排序。量化性能声明~4x faster是 mid 档的准入条件之一但排序准则不负责核实声明真伪——SKILL.md Phase 4 的 Accuracy 阶段会要求对量化声明对照实现与文档验证必要时用uv run运行临时脚本内核脚本必须是真实文件而非python -c并对涉及原生代码变更的声明先重建二进制。该准则是 Warp 内部发版流水线的组成部分.claude/skills/下的技能参考文档其他项目可直接移植其三档影响 软性聚簇 绝不降级的方法论但wp.*符号示例与 Towncrier 配置细节需按各自仓库调整。小结《Impact Sorting Rubric》用一份高度可操作的规则把发布章节条目顺序从审美问题变成了可裁决的评分问题High/Mid/Low 三档覆盖新 API、互操作边界、破坏性变更、默认值变更、平台支持等硬性判据同档内以主题聚簇和具体性作软性裁决并以绝不降级为硬约束防止聚簇绑架优先级。配合 pyproject.toml 中固定的 Towncrier 渲染配置与 CHANGELOG.md 的既有发布形态这套准则让 Warp 的每次发版条目在信息密度与阅读顺序上都保持了一致的用户影响优先原则。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考