Warp 变更日志 Fragment 语言规范实战指南：从收录判定到语句润色的完整工作流-平芜编程栈

Warp 变更日志 Fragment 语言规范实战指南：从收录判定到语句润色的完整工作流

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

本文基于 Warp 仓库中.codex/skills/warp-changelog-audit/references/language-conventions.md这一权威规范文档，系统讲解 Warp 变更日志 fragment（即changelog/目录下的待发布条目）应如何判定收录范围、规避内部术语、统一符号格式、标记实验性功能并落实祈使语气与连字符等语言约定。读完本文，你将掌握一套可机械执行的语言审查（language pass）流程，能在发布前将杂乱的提交记录整理成用户可读、可检索、可引用的 CHANGELOG 条目，并理解其背后的 Towncrier 渲染机制与仓库配套规范。

背景：Warp 的 Towncrier 变更日志体系

Warp 使用 Towncrier 目录下提交小型 fragment 文件，由 pyproject.toml 中的[tool.towncrier]配置在发布时聚合渲染：

[tool.towncrier] directory = "changelog" filename = "CHANGELOG.md" start_string = "<!-- towncrier release notes start -->\n" title_format = "## [{version}] - {project_date}" issue_format = "[GH-{issue}](https://github.com/NVIDIA/warp/issues/{issue})" issue_pattern = "\\d+" wrap = false ignore = []

其中issue_format定义了渲染时自动追加的 issue 链接格式，directory映射六个分类：added、removed、deprecated、changed、fixed、documentation（pyproject.toml）。也就是说：issue 链接由 Towncrier 自动生成，fragment 正文里不应手写——这正是本规范文档反复强调的前提。

语言规范文档本身由 warp-changelog-audit/SKILL.md 在语言审查阶段（Phase 5）加载，与 sorting-rubric.md（决定最终生成章节的排序）配合使用。fragment 的命名与分类权威规则见 changelog/README.md，语言规范则负责"什么能写、怎么写、怎么改"。

什么该写进 fragment：收录判定标准

属于 fragment 的内容

一个 fragment 只承载对用户可见的变更，具体包括：

新增、移除、弃用或改变的用户可见 API：函数、类、装饰器、标量类型、kernel 内置函数、配置开关；
破坏性变更（必须带**Breaking:**标记）；
用户可观察行为的 bug 修复；
新的顶层文档：全新的用户指南页面、新示例、新的 doctest 驱动参考文档（注意：已有页面上的笔误修正不属于此列）；
跨越用户可见阈值的性能变化：默认优化级别、默认代码生成路径、默认对齐行为；
平台 / Python / 依赖支持变化：如放弃 Python 3.9、提升最低 CUDA Toolkit 版本、提升最低驱动版本。

仓库中的真实 fragment 可以印证这一标准。例如 1691.added.md 属于"新增用户可见 API"：

Add support for allocatingvec4dvolumes withwp.Volume.allocate()andwp.Volume.allocate_by_tiles().

不属于 fragment 的内容

以下内容不应该出现在 fragment 中：

测试相关：测试新增、测试重构、测试运行器改进（凡是在warp/tests/**或warp/_src/tests/**之外无任何足迹的内容）；
无用户可观察效果的内部重构："Reorganize private helpers"、"Move foo from bar to baz"、"tidy up X"（无 API 增量）；
CI 配置变更（.gitlab-ci.yml、.github/workflows/**）；
不改变打包或运行时的构建系统打磨；
单条 doctest 修正、单句文档措辞调整、错误消息措辞微调（除非该消息措辞本身是文档化契约的一部分）。

默认策略：拿不准就 drop

If unsure, default todrop. Release notes andgit logcapture the long tail. The CHANGELOG is the curated user-visible manifest.

这句话点明了整个收录判定的价值取向：CHANGELOG.md是经过策展的用户可见清单，而长尾细节由 release notes 和git log承载。宁可漏收（日后可补），也不要让非条目混入发布说明——发布说明会被从该文件中抓取，多余条目只会增加噪音。

内部术语标记：从用户视角剔除实现细节

语言审查最重要的动作之一，是标记并处理包含内部术语的条目。规范文档给出了三类需要标记的线索：

标记类别	判定线索	示例
内部模块路径	`warp._src.`、下划线前缀包内的一切；`warp.context.`（无前缀模块只是向后兼容 shim，不是公共 API）	"Refactor`warp._src.codegen`to share emit path."
C++/CUDA 内部类型名	`launch_bounds_t`、`tile_register_t`、`exec_mode_t`，以及一切以`_t`结尾的私有 C++ 类型	"Update`launch_bounds_t<N>`template..."
私有标识符	任何前导下划线标识符（`_compile`、`_resolve`、`Module._foo`）	"Move private`_resolve_dtype`from`warp._src.context`..."
面向用户的行文中出现"仅实现"动词	"refactor internal"、"reorganize private"、"move helper"、"split class"——用户无法对这些动作采取行动	"Add helper`_validate_launch_dims`for kernel launch checks."

被标记的条目的处置原则是：

若存在真实的用户可观察效果（例如该重构修复了一个偶发 bug，或改变了某个默认值），则改写（rewrite），把重点落到用户能感知的结果上；
若没有用户可观察效果，则删除（delete）。

符号格式约定：让 CHANGELOG 脱离仓库语境仍可读

CHANGELOG 是在脱离仓库上下文的情况下被阅读的，因此符号格式化必须一致，否则会误导浏览者。规范文档列出了六条硬性约定：

Python 符号必须带模块限定：写wp.tile_load()，绝不写裸tile_load()；写warp.fem.IntegrationOrder，绝不写裸IntegrationOrder。不带限定名的符号无法告诉用户它住在哪个模块。
函数和方法必须带括号：写wp.tile_dot()，不写wp.tile_dot。括号传达"这是可调用的"，并区分函数引用与类/类型引用；即使条目不列出参数，也要写()。
短签名可内联以增加价值：当条目宣布新参数时，wp.tile_load(addr, shape, ..., aligned=True)比wp.tile_load()更有用；但若条目已在行文中点名所有相关参数，就不要再渲染完整签名。用字面三个点...省略无关参数。
子模块符号使用模块相对限定：写warp.fem.X（完整点分路径），不写wp.X。wp.短形式保留给warp命名空间下的顶层公共 API。
装饰器加@前缀：写@wp.kernel、@wp.struct、@wp.func。当符号是装饰器时，绝不写裸名wp.kernel。
引用类型本身时类型名不加括号：wp.array、wp.bfloat16、wp.float64（无括号）。但当类型被当作构造器调用时（wp.array(data, dtype=wp.float32)），括号是正确的，因为那是调用表达式。
审查时的一致性检查：当单一条目引用多个符号时，所有符号必须遵循同一约定。例如 "Addwp.tile_dot()and improve performance oftile_load" 应改写为 "Addwp.tile_dot()and improve performance ofwp.tile_load()"。

这些约定适用于每一个待处理 fragment；不得改写CHANGELOG.md中的历史章节——它们是已发布的发布记录。

Markdown 反引号而非 RST 双反引号

这是一个容易踩坑的语法差异点。Warp 的 docstring 使用 RST，行内代码要求双反引号（依据 AGENTS.md：``data``、``.nvdb``）。而 changelog fragment 是 Markdown，单反引号（`foo`）才是约定；若在 fragment 中使用双反引号，生成的CHANGELOG.md里会按字面渲染，读者会看到``foo``而不是等宽代码。

检测规则是纯机械的，不需要逐条提示：

匹配任何待处理 fragment 中的 X，其中X不含反引号 → 改写为`X`；
不要动…（双反引号包裹着本身含单反引号的代码）——这是包含字面`的代码的合法 Markdown 形式；
不要动围栏代码块（三反引号围栏 ```），语法完全不同；
不要清扫已发布章节。

该修复无需逐条请求用户确认，对全部待处理 fragment 执行即可，报告数量并纳入合并 diff。

仓库中恰好有正反两个实例可对照：1691.added.md 使用单反引号`vec4d`、`wp.Volume.allocate()`，符合 Markdown 约定；而 1792.deprecated.md 中出现了 BsrMatrix.copy_nnz_async() 这样的 RST 双反引号残留，正是规范要求机械修正的典型目标。

实验性功能标记：用`Experimental:`替代模糊对冲

Warp 用字面的**Experimental**:前缀（或**Experimental:**）标记实验性功能，规范以 cuBQL BVH 后端为典范示例：

**Experimental**: Add cuBQL BVH backend for \wp.Mesh`, selectable via `bvh_constructor="cubql"`.`

这个粗体标记是传达"该表面在稳定前可能变化"的唯一一致方式——行文中的非正式措辞会模糊界限，并被寻找稳定变更的用户遗漏。

需要标记的对冲词

以下对冲词出现在条目中时会被标记：

preliminary（如 "preliminary support for X"）
early/early access/early support
alpha/beta（修饰功能时；版本号1.0.0-beta不算）
tentative
WIP/work-in-progress
draft（修饰功能时；字面意义的未完成文档不算）
provisional
experimental（小写，或大写但没有**…**粗体标记——如Experimental JAX kernel callback support或行尾(experimental)）

改写为规范形式

给条目加上**Experimental**:前缀，并从行文中删掉对冲词：

原文	改写结果
Add preliminary graph capture support for serialization (APIC) and CPU replay.	Experimental: Add graph capture support for serialization (APIC) and CPU replay.
Experimental JAX kernel callback support	Experimental: Add JAX kernel callback support.
Add`wp.foo()`(early access)	Experimental: Add`wp.foo()`.

关键流程约束：在暂存改写之前必须向用户确认。添加**Experimental**:标记是公开的稳定性信号——它向用户传达"此功能可能变化"。不要单方面应用；应展示原文与拟改写，让用户确认该功能确实是实验性的，而不仅仅是用对冲措辞描述。

不要仅为添加标记而批量改写已发布章节；此改写只针对待处理 fragment。

祈使语气：让条目以行动动词开头

fragment 正文以祈使语气动词开头，一致的语态让用户能快速扫读生成的发布章节：

✅ 正确示例：

"Addwp.tile_dot()for tile dot products."
"Fix crash inwp.tile_load()for non-contiguous arrays."
"Switch CPU JIT linker from RTDyld to JITLink."
"Reduce kernel register pressure for low-dimensional launches."

❌ 错误示例及改法：

错误写法	问题	正确改法
"Added`wp.tile_dot()`..."	过去时	"Add`wp.tile_dot()`..."
"Adds support for ..."	现在时直陈	"Add support for ..." 或 "Support ..."
"`wp.foo()`now does X"	直陈句	"Make`wp.foo()`do X" 或 "Update`wp.foo()`to do X"
"X is now experimental"	被动	"Mark X as experimental"
"X has been deprecated"	被动过去时	"Deprecate X"

各分类的常用祈使动词清单：

Added：Add、Allow、Support、Expose、Re-export、Re-enable
Removed：Remove、Drop、Retire、Discontinue
Deprecated：Deprecate、Mark
Changed：Change、Update、Switch、Replace、Promote、Move、Rename、Reduce、Improve、Restore、Pin、Make、Apply、Require
Fixed：Fix、Correct、Handle、Resolve、Address
Documentation：Document、Add、Update、Polish

对于以**Breaking:**或**Experimental**:标记开头的条目，祈使动词跟在标记之后："Breaking:Changewp.foo()..."。标记只是前缀，祈使语气规则依然作用于其后紧跟的动词。

连字符：复合修饰语的标准英语连字符规则

CHANGELOG 面向扫读的用户，连字符的缺失或多余都会干扰阅读。

何时使用连字符

两个及以上词构成名词前的复合修饰语时使用连字符：

"user-facing API"
"16-byte alignment"
"thread-block stack"
"low-dimensional kernels"
"per-thread cooperative add"
"non-trivial change"（技术行文中non-前缀连字符化）
"out-of-place factorization"、"in-place update"

何时不使用连字符

谓语位置（系动词 is/are/was 之后）不加连字符："the API is user facing"、"the value is 16 bytes"（复数）、"the operation is out of place"；
已确立的开放复合词不加："machine learning model"（"machine-learning model" 在技术行文中也可接受——选定一种并在节内保持一致）、"data structure"、"host memory"、"device memory"。

Warp 特例

"GPU-side"、"CPU-side"、"host-side"、"device-side"——作修饰语时连字符化；
"16-bit"、"32-bit"、"64-bit"、"128-bit"——类型位宽始终连字符化；
"JIT-compiled"——连字符化；
"ahead-of-time"（compiled）——连字符化；
"N-D" / "2-D" / "3-D"——作修饰语时连字符化（"N-D tiles"）。

判断情形：拿不准时，遵循待处理 Towncrier 草稿中的主流模式，不要发明罕见的连字符用法。

GitHub issue 链接：交给文件名与 Towncrier

不要把 GitHub issue 链接写进 fragment 正文。数字文件名如1364.added.md会告诉 Towncrier 在渲染时追加[GH-1364](https://link.gitcode.com/i/43c6a3d6c7679dffeb209735f6a83738) 的issue_format` 配置驱动。

具体规则：

一个变更解决多个 issue：每个 issue 保留一个 fragment，内容完全相同。Towncrier 会把它们合并成一条 bullet 并追加全部链接（参见 changelog/README.md 的说明）；
删除与数字文件名重复的手写 GitHub issue 链接；
其他内容链接（如迁移指南）仍然允许；
在最终生成的发布章节中，排序与折行时要保留 Towncrier 生成的 issue 链接在 bullet 末尾。

Worked rewrites：实战改写对照表

规范文档提供了逐条对照，是语言审查最直接的执行参考：

原文	动作	结果
Refactor`warp._src.codegen`to share emit path.	删除	无用户可观察效果。
Update`launch_bounds_t<N>`template to reduce register pressure.	改写	"Reduce kernel register pressure for low-dimensional launches."
Move private`_resolve_dtype`from`warp._src.context`to`warp._src.types`.	删除	内部符号，未导出。
Switch CPU JIT linker from RTDyld to JITLink, fixing sporadic access violations.	保留	已面向用户——点名了症状，而非实现。
Add helper`_validate_launch_dims`for kernel launch checks.	删除	私有辅助函数。
Move`wp.utils.RmmAllocator`to`wp.utils.AllocatorRmm`.	保留（这就是重命名）	公共符号；重命名对用户可见。
Add preliminary graph capture support for serialization (APIC) and CPU replay.	改写	"Experimental: Add graph capture support for serialization (APIC) and CPU replay."（对冲词 → 规范标记）

保留 issue 身份

改写 fragment 内容时，必须保留其数字标识符（文件名中的数字或+slug）。若多个数字 fragment 有意共享一条 entry，保持内容完全一致。绝不把 Towncrier 生成的 issue 链接复制进 fragment 文本。

用户视角子代理审查：处理歧义条目的标准流程

对真正含糊的条目，规范定义了一个标准流程：派发一个"典型 Warp 用户"子代理，使用如下逐字提示词（canonical）：

You are a typical Warp user. You write CUDA-style kernels in Python via `@wp.kernel`, allocate `wp.array`s, and read the CHANGELOG when a new release lands to decide whether your code is affected. You have not read the Warp source code. Reading ONLY this entry, with no other context: <verbatim entry text> Answer in 3 short bullets: 1. What does this change mean for code I have written today? 2. What words or phrases in this entry are unclear, or assume knowledge I don't have? 3. Does the entry mention internal implementation details that a user shouldn't need to understand? Be honest: if the entry is opaque, say so plainly.

利用响应做出决策：

三个 bullet 都表明用户理解、影响清晰→原样保留（keep as-is）；
bullet 2 或 3 标记了行话或模糊框架→改写（rewrite）（由你起草；子代理不负责起草改写稿）；
bullet 1 表示"对我无影响 / 我看不出来"且没有其他信号表明用户可见变更→删除（delete）。

流程优化提示：单次审计的所有子代理应在一个并行批次中派发（一条消息多个 Agent 工具调用），不要串行——墙钟时间很重要，且子代理相互独立。

判断哲学：drop、ask、keep 的平衡

规范以四条原则收束整个语言审查工作流：

拿不准倾向"drop, don't keep"：不属于的条目不保留。日后想补回 CHANGELOG 条目随时可以；而非条目一旦发布，就会给从该文件抓取的 release notes 增加噪音。
非平凡改写倾向"ask, don't auto-edit"：机械过滤器可以自信地删除；对边界条目的改写，走子代理步骤。不要擅自改写。
绝不编造事实：若条目声明看起来有误（如 GH 引用与主题不符），在最终报告中标记，而不是静默围绕它改写。
保留好的内容：若条目已经清晰、面向用户、范围得当，标记为保留即可。语言审查不是重写已可用行文的借口。

与其他阶段衔接：语言审查在发布流程中的位置

语言规范不是孤立文档。它在 warp-changelog-audit/SKILL.md 的 Phase 5（语言审查）中被加载，与以下环节构成完整发布流水线：

Phase 3 的缺失 fragment 恢复：从git log枚举提交，映射到 fragment，测试/CI/内部重构直接丢弃；
Phase 4 的验证与合并：先验证新 API、破坏性变更、量化声明与实现一致；同一功能发布前的多次迭代合并为一条描述最终状态的 entry；
Phase 5 的语言审查：本规范全量执行——删除内部条目、改写内部行话、规范化反引号/祈使语气/连字符/稳定性标记/公共符号格式、折行不超过 120 列；
Phase 6 的发布定稿：按 sorting-rubric.md 在生成章节内按用户影响高→低排序（同类目内以主题聚类为软决胜项），折行至多 120 列，维护比较链接块。

所有暂存改动先在临时目录中渲染 Towncrier、展示合并 diff 与草稿，等待明确确认后才写入工作区。整个流程的核心一致性贯穿始终：fragment 是来源，CHANGELOG 是经过策展的发布记录，语言规范则是让这份记录对用户真正可读、可检索、可引用的质量闸门。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Warp 变更日志 Fragment 语言规范实战指南：从收录判定到语句润色的完整工作流