Warp 发布说明风格规范全解析:从 `NNNN` 引用到可运行代码示例的成文准则

原创2026-10-10 23:23:061,626 阅读
文章标签:高性能计算科学计算物理引擎机器学习深度学习编译器图形学机器人

Warp 发布说明风格规范全解析:从 #NNNN 引用到可运行代码示例的成文准则

导读

本文系统讲解 NVIDIA Warp 项目用于编写 GitHub 发布说明(release notes)的完整风格规范,内容源自仓库内 .codex/skills/warp-release-notes/references/style-rules.md(该文档本身由 Warp v1.10 至 v1.12.1 的已发布说明与用户偏好提炼而成)。读完本文,你将掌握一套可直接复用的发布说明写作方法:如何引用 issue/PR、如何使用 GFM 告示块标注实验特性、如何按影响力排序组织章节、如何为每个新 API 配可运行代码示例,以及如何区分"给代码评审者的 CHANGELOG"与"给 Python 用户的发布说明"。文中所有规则均以仓库源码、CHANGELOG 与测试用例为佐证,可直接对照实践。

发布说明在 Warp 中的定位与来源

Warp 仓库通过 Towncrier 收集变更片段:PR 或 MR 会在 changelog/ 目录下添加小文件(如 2038.added.md、2010.fixed.md),而不是直接编辑 CHANGELOG.md。片段文件名由 GitHub issue 号加类别后缀组成,类别按 added、removed、deprecated、changed、fixed、documentation 的顺序渲染;没有对应 issue 的条目使用 + 前缀的可读标识符(例如 +clarify-array-docstring.documentation.md,参见 changelog/README.md)。

配套的 .codex/skills/warp-release-notes/SKILL.md 将发布说明生成拆成六个阶段:解析目标版本与前一版本标签、与用户确认范围与输出位置、收集片段与贡献者归属、规划分组并核查实现、起草各小节、渲染并写入目标(本地文件或 GitHub gist)。而 style-rules 这份文档,正是 Phase 6 渲染阶段必须严格遵守的硬性约束清单。

本仓库当前版本为 1.19.0.dev0(见 VERSION.md),发布说明面向的是"从 Python 使用 Warp 的开发者"这一受众。

GitHub issue / PR 引用:一律使用纯 #NNNN

发布说明与 CHANGELOG 的引用风格刻意不同:

  • 发布说明:使用纯文本 #NNNN,不要使用 [GH-NNNN](https://github.com/NVIDIA/warp/issues/NNNN) 方括号链接形式。原因是发布说明张贴在同一个 GitHub 仓库内,GitHub 会自动把 #NNNN 解析为可点击链接并在悬停时显示 issue/PR 标题;方括号形式是为在 GitHub 之外消费的 CHANGELOG.md 准备的,放进发布说明会显得笨重。
  • 一条 bullet 涉及多个 issue 时,用逗号分隔、每个都带 # 前缀,例如 Tile programming gains new primitives (#1287, #1298, #1342, #1364).。
  • 不要去掉 # 前缀:#NNNN 会让 GitHub 渲染出 issue 标题或 PR 标题,两者都有用。

反例(禁止):Fix kernel cache serving stale binaries when compilation settings change ([GH-903](https://github.com/NVIDIA/warp/issues/903)).

对照仓库中的 CHANGELOG.md 可以看到,GH-XXXX 链接形式正是用于 CHANGELOG 主体的,例如 ([GH-1797](https://github.com/NVIDIA/warp/issues/1797));而发布说明则应换成纯 #1797 形式,两种文体各司其职。

告示块:只使用 GFM 五种规范形式

需要视觉分隔的信息,一律使用 GitHub Flavored Markdown 的 alert 块,五种规范形式为:

> [!NOTE]      — 有用的背景信息,即便略读也值得看
> [!TIP]       — 帮助做得更好/更省力的建议
> [!IMPORTANT] — 用户达成目标所需的关键信息
> [!WARNING]   — 需要立即注意以避免问题的紧急信息
> [!CAUTION]   — 某些行为带来的风险或负面后果

禁止使用临时拼凑的形式,它们在渲染后的发布页上会显得突兀:

❌ > **Note:** Useful background...
❌ **Note:** Useful background...
❌ > _Note:_ Useful background...
❌ > ⚠️ Warning: ...(应改用 > [!WARNING])

✅ 正确写法:

> [!NOTE]
> Useful background...

选择告示类型要看意图而非 emoji 偏好:[!IMPORTANT] 用于用户成功所需的信息(实验状态、破坏性变更迁移路径);[!NOTE] 用于附带背景;[!CAUTION] 用于读者可以规避的风险提示;[!WARNING] 用于忽略就会出问题的事项。每篇文章限制在一到两个告示块,且不要连续堆叠两个告示块。

实验特性标注:### 标题下紧跟 > [!IMPORTANT]

当一个 ### … 小节描述的特性在 CHANGELOG 条目中带有加粗的 **Experimental** 标记时,在该标题下立即放置 > [!IMPORTANT] 告示块,形状必须精确如下:

### Graph capture serialization and CPU replay

> [!IMPORTANT]
> This is an experimental feature. The API may change without a formal deprecation cycle.

Warp 1.13 introduces ...

用户偏好对实验状态使用 [!IMPORTANT] 而非 [!WARNING] 或 [!NOTE]:该特性真实存在、值得试用,只是稳定性门槛低于正式 API。

两条重要边界:

  • 按特性放置,不按分组放置。如果整个发布中还有依赖同一子系统的非实验特性,不要把告示放在分组级别(例如不要放在 ## Graph capture 之上),而是放在每个具体实验特性的 ### 块上,让扫读标题的读者一眼看出哪些子特性有稳定性提醒。
  • 目录或引言中的行内提及,用括号 (experimental) 追加,例如 experimental graph capture serialization,而不是 **EXPERIMENTAL** graph capture serialization。

先说"解锁了什么",再提 API 名称

每个特性描述的第一句话都应回答:过去做不到、现在能做到什么? API 名称放在支撑句里,不要放在开头。

❌ 反面:Warp 1.13 adds capture_save() and capture_load() functions for graph serialization, plus a new wp.handle scalar type.

✅ 正面:Warp 1.13 introduces a portable serialized-graph format. Graphs captured in Python can now be saved to a .wrp file with capture_save() and replayed from either Python or standalone C++ via capture_load(), enabling cross-process and cross-language graph reuse. A new wp.handle scalar type carries mesh handles across load.

这条规则同时适用于开头段落与主特性的 ### … 块。API 名称不可避免,只是要放在解锁能力之后。

章节组织:同类聚合、按影响力排序

聚合相似特性

同类特性必须归在一起:tile 原语放一起,JAX 特性放一起,warp.fem 特性放一起。即便 CHANGELOG 中它们是带不同 GH 引用的独立条目,发布说明也要合并。分组反映的是用户如何思考特性("我在做 tile 相关的工作"),而不是代码库如何组织它们。

✅ 正确——单一主题章节:

## New tile primitives

This release adds several tile primitives that shorten common kernel patterns:

- `wp.tile_dot()` (#1364) replaces the longer
  `wp.tile_sum(wp.tile_map(wp.tensordot, a, b))` form for ...
- `wp.tile_axpy(alpha, src, dest)` (#1363) fuses the in-place update ...
- `wp.tile_scatter_add()` (#1342) and `wp.tile_scatter_masked()` (#1298) ...

❌ 反面——三个各自描述一个 tile 原语的独立 ## … 章节。

这条规则在源码中有直接对应:wp.tile_dot() 的文档字符串(warp/_src/builtins.py)明确说明其等价于 wp.tile_sum(wp.tile_map(wp.dot, a, b)) 但免去了中间 tile 与共享内存往返;wp.tile_axpy()、wp.tile_scatter_add()、wp.tile_scatter_masked() 均定义于同一文件(warp/_src/builtins.py 附近),按"tile 原语家族"聚合正是发布说明的应有形态。

按影响力排序

每个发布内,小节大致按以下顺序:

  1. 主特性——值得在 ## New features 顶部拥有独立 ## … 块的一两个条目;
  2. 其他新特性与主题分组(tile、JAX、fem 等);
  3. 性能改进(如果幅度可观);
  4. 语言增强 / 编译工具链;
  5. 新示例(如有值得提的);
  6. Bug 修复(仅限值得单独强调的;CHANGELOG 已收录全部);
  7. 公告(弃用、平台支持);
  8. 致谢。

主特性由用户在范围确认时指定,或由技能作者从 CHANGELOG 中判定最令人兴奋的一项。

标题写法

章节标题(## …、### …)要短、描述性强、有动作感;它们是短语而非句子——不加句号、不写完整散文。

  • ✅ ### Graph capture serialization and CPU replay
  • ❌ ### Adding graph capture serialization with CPU replay support.

特性块内部的子标题(如 "Key capabilities")用加粗段落标签加冒号,不要使用独立的 #### 标题:

**Key capabilities:**

- 1D / 2D / 3D ...

代码示例:默认配备,而非例外

每个新 API 都要有可运行示例

描述新公共 API 或行为变更的每个 ### … 块,都要附带一个可运行的 Python 代码块,展示最简单而有意义的用法:

  • 顶部放导入(import warp as wp 等);
  • 不要调用 wp.init()——Warp 在首次使用时隐式初始化,示例中调用 wp.init() 是过时写法,即便是旧发布说明里出现的也要删掉;
  • 一段短 kernel 或调用序列;
  • 展示程序输出(见下文"输出渲染")。

示例必须是能跑的代码而非伪代码,目标 5-15 行。

输出渲染:单行用尾注,多行用独立 text 块

程序输出按长度与结构选两种形态之一:

  • 单个短值 → 在 print(...) 行尾加 # 注释,适用于一行就能容纳的标量/数组输出:

    print(out.numpy()[:8])  # [0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5]
    
  • 多行或有结构的输出 → Python 块之后紧跟独立的 fenced ```text 块,前面加一行简短说明。表格、多行转储、带命名的分段报告等需要纵向扫读的输出都应如此;把多行输出埋进 kernel 代码里的 # 注释会埋没特性价值。示例:

    with wp.ScopedMemoryTracker("training step"):
        train_step(model, batch)
    

    Output:

    === Memory tracking summary: training step ===
      GPU peak:    1.42 GiB
      GPU current: 612 MiB
      Top allocations:
        [model.parameters]      512 MiB  (12 calls)
        (native:bvh)            256 MiB  (3 calls)
        [batch.activations]     128 MiB  (8 calls)
    

    第二个块必须用一行短说明("Output:"、"Prints:"、"Result:")引导,并与 Python 块之间空一行,让渲染页面上的对应关系一目了然。

判断阈值:输出只有一行短内容用行内注释;输出跨 2 行以上或具有内部结构(行、表格、key:value 对、嵌套缩进)就用独立 text 块。读者永远不该需要在大脑中重新排版 # 注释块才能看懂打印了什么。

示例输出必须真实运行验证

发布说明中每个可运行的 Python 片段,在草稿送审前都必须端到端执行一遍。 这不是"当输出本身就是特性时才要求",而是默认要求。运行每个片段的成本约 1 分钟;把坏片段发进已发布的发布说明,代价是信誉。

对每个片段的标准流程:

  1. 将片段原样保存到 /tmp/release_notes_example_<short-name>.py;
  2. 在仓库根目录用 uv run /tmp/release_notes_example_<short-name>.py 运行,完整捕获 stdout;
  3. 把捕获到的输出嵌入发布说明(单行 → 行尾 # 注释;多行/结构化 → 独立 ```text 块);
  4. 完成后删除临时文件。

片段跑失败就修片段(是片段有 bug),然后重跑。不要手打预期输出、不要转述输出"应该"是什么样、不要编造看似合理的数字。 只有实际运行才能发现的 bug 类型(举例、非穷尽):旧文档未暴露的缺失必需关键字参数;在预期 wp.ScopedDevice 作用域之外创建数组导致的设备不匹配;print(...) 渲染形式泄漏内部 warp._src.* 路径;手打预期输出与实际渲染不符。

当输出本身就是被演示的特性时,输出渲染不可妥协:

  • wp.ScopedMemoryTracker / wp.config.track_memory——作用域退出时打印的分配汇总就是该特性的头条价值,要在独立块中展示真实表格;
  • wp.print_diagnostics()——格式化的环境转储就是全部意义所在,转储要用 text 块渲染;
  • bfloat16 / fp64 提升——短的 dtype 确认可以用行内尾注注释形式;
  • 近似数学内建函数——并排的数字差异足够短可以行内;多行精度表属于 text 块。

仓库佐证:wp.ScopedMemoryTracker 实现在 warp/_src/utils.py,文档字符串明确说明它拦截 C++ 原生层的 wp_alloc_* / wp_free_* 调用,因此 Python 发起的与 C++ 内部(BVH、HashGrid 等)的分配都会被捕获,Python 分配还带调用点文件、行号与函数名;wp.config.track_memory 开关定义在 warp/config.py,且 wp.init() 在启用时会推送 "global" 作用域并在解释器退出时停止跟踪(warp/_src/context.py)。wp.print_diagnostics() 定义于 warp/_src/context.py,返回并打印 Warp Python/原生版本、LLVM/clang 版本、NumPy 版本、可选框架版本(torch、jax、jaxlib)、Python 与平台信息、CUDA 工具链(toolkit、driver、nvrtc、兼容性开关)、mathdx/cuBQL/nanovdb 状态、CPU 名称与特性集、构建标志(debug、verify_fp、fast_math、sanitizer)以及设备列表——这正是文档要求"用 text 块渲染整个转储"的原因。可参考的实战示例见 warp/examples/core/example_alloc_tracker.py,测试见 warp/tests/test_allocation_tracker.py。

何时可以只用散文: 唯一合理豁免是单参数整理、单标志开关、或纯性能优化(无 API 变化)。拿不准就放片段。过往评审反复把"这一节全是 bullet 没有代码"列为首要投诉,默认放片段就是解药。

对于聚合多个相关新 API 的章节(如 "New tile primitives"),每个具名 API 各配一段短片段,而不是合并成一个大转储。片段可以共享一个明显的 setup,但每个新符号的调用点都要逐字展示。

跨语言/跨运行时特性:两侧都要有片段

任何跨越语言或运行时边界的特性声明,都必须在每一侧都带片段,而不只是 Python 作者侧:

  • Python → 独立 C++(例如图捕获序列化):一个 Python …_save 片段加一个最小 C++ 片段展示消费侧(头文件、初始化顺序、load + replay 调用)。如果 warp/examples/cpp/ 下存在可用的树内示例,以发布标签的相对 URL 链接它。
  • Python → JAX:一段 Python kernel 定义加一个 jax_kernel(...) 绑定,展示消费侧的导入与调用模式。
  • Python → PyTorch / DLPack:展示消费侧往返(wp.from_torch / __dlpack__)的片段。

点名消费侧的头文件名或导入路径不是可选项。只看到生产侧的读者无法判断该特性是否解决他们的问题。

破坏性变更用 before/after 片段

## Bug fixes、## Changes to existing APIs 或任何宣布行为转变的章节中的破坏性变更,必须配 before/after 代码块而非散文,并用注释头(# v1.X behavior: / # v1.Y migration:)明确意图:

# v1.12 behavior: out.grad still holds the seed after backward()
out = wp.zeros(N, dtype=float, requires_grad=True)
with wp.Tape() as tape:
    wp.launch(forward_kernel, dim=N, inputs=[x], outputs=[out])
out.grad = wp.ones_like(out)
tape.backward()
print(out.grad)  # v1.12: ones, v1.13: zeros

# v1.13 migration: keep output grads, pass fresh seeds each call
out = wp.array(shape=N, dtype=float, requires_grad=True, retain_grad=True)
with wp.Tape() as tape:
    wp.launch(forward_kernel, dim=N, inputs=[x], outputs=[out])
tape.backward(grads={out: wp.ones_like(out)})

迁移散文写得再清楚,用户也只能猜测字面调用形状;before/after 片段消除了猜测。

按变更形态选围栏语言:

  • 迁移跨多行、需要新 setup 或展示行为转变时(例如 .grad 读取现在归零、默认值变化、输出现在要求 retain_grad=True),用两个 ```python 块加 # v1.X behavior: / # v1.Y migration: 注释头——两块形式承载了 diff 视图会拆散的导入、作用域与完整调用上下文。

  • 变更只是紧凑的签名位移、参数重命名或单行调用点更新时,用单个 ```diff 块,- 行标旧形态、+ 行标新形态,GitHub 会以红/绿高亮让差异一目了然:

    - m = wp.matrix_from_rows(wp.vec2(1, 2), wp.vec2(3, 4))
    + m = wp.mat22(wp.vec2(1, 2), wp.vec2(3, 4))
    
    - wp.tile_load(arr, shape=N, offset=i * N)
    + wp.tile_load(arr, shape=N, offset=i * N, aligned=True)  # new opt-in flag
    

    把 diff 块留给读者 1-3 行内能吸收的变更;更大的变更用两个 python 块,因为 diff 语法高亮会丢失 Python 着色(只有行首 +/- 着色),长迁移代码读起来更差。

tile_load 的 aligned 参数在源码中有真实对应:warp/_src/builtins.py 会校验 aligned=True 对 storage='register' 的 tile 无效果(只影响共享内存 tile),并将 register tile 强制回退为 aligned=False——这正是"新 opt-in 标志"类变更适合单 diff 块呈现的典型例证。

链接树内示例

特性在 warp/examples/** 下有可用示例时,要显式链接,并在 URL 中使用发布标签以免漂移:[example_name](https://github.com/NVIDIA/warp/blob/v<version>/warp/examples/<path>)。绝不用 SHA 链接,也绝不用 main 链接;如果链接会指向在该标签下已移动或消失的文件,就放弃该链接。

特性产出的磁盘产物

特性写入新的磁盘产物(文件格式、序列化图、检查点)时,要描述显而易见的文件之外还写了什么。旁挂目录、版本固定的二进制、架构固定的 CUBIN 是常见坑:用户只发布 name.wrp 而缺 name_modules/ 目录,会遭遇静默加载失败。产物不止一个文件时,用字面目录树代码块:

scene.wrp                 # operation byte stream + region snapshots + metadata
scene_modules/
    abc123.cubin / .meta  # one per kernel module, arch-pinned

专有名词与标点

专有名词大写

以下名词一律大写:NumPy、Warp、NVIDIA、CUDA、JAX、PyTorch、Python、OpenGL、Linux、Windows、macOS、Apple Silicon、ARM64、x86_64。正文中不得小写;唯一例外是代码反引号中引用字面符号(反引号内的 numpy.float32 是允许的)。

不用破折号

正文不用 em dash(—),改用逗号、句号或冒号。这是 Warp 发布说明风格的既定用户偏好:

  • ❌ Warp v1.13 introduces graph capture serialization — letting captured graphs roundtrip ...
  • ✅ Warp v1.13 introduces graph capture serialization, letting captured graphs roundtrip ...
  • ✅ Warp v1.13 introduces graph capture serialization. Captured graphs can roundtrip ...

该规则作用于渲染输出;反引号括起的代码或外部来源的逐字引用中的破折号豁免。

正文标点

  • 避免 em dash(见上);
  • 避免正文分号。它们在排版上比通常所需的间隔更重,除非两个分句强平行且并列更有意义,否则转为句号。代码块中的分号(C++ 语句终结符)不受影响。

复合修饰语连字符

两个及以上单词共同修饰一个名词时加连字符:"ray-heavy workloads"、"shared-memory tile"、"host-CPU specialization"、"Warp-based renderer"、"header-only library"、"power-of-2 tile sizes"、"16-byte alignment"、"multi-byte elements"。

片段中的下标式类型标注

tile/array 参数标注用下标式:

  • x: wp.array[float](不是 wp.array(dtype=float))
  • A: wp.array2d[float](不是 wp.array2d(dtype=float))
  • t: wp.tile[float](不是 wp.tile(dtype=float))

旧式调用语法在 v1.12 于用户代码中弃用(#1216),因为 Pyright 等静态类型检查器会把它当作构造函数调用。发布说明片段应使用现代形式。仓库佐证:wp.array<a href="https://link.gitcode.com/i/3046d0aeae4efef4c47d7fb2bb4da3cb" target="_blank">float] 等下标式用法遍布内核签名与文档示例(如 [warp/_src/builtins.py 的 out: wp.array<a href="https://link.gitcode.com/i/4d4e31a6133a19298b80084db17aa1f7" target="_blank">float]),类型体系通过 __class_getitem__ 实现下标支持([warp/_src/types.py 展示了 Vector[dtype, length] 等泛型类的实现模式)。

非 Python 片段对齐树内惯例

C++/CUDA 片段的注释与结构惯例要匹配该特性树内示例的写法。

Warp 词汇

使用 Warp 自己的术语,不借用其他框架的词:

  • ✅ tile、array、kernel、struct、builtin(Warp 的说法);
  • ❌ tensor(PyTorch)、ufunc(NumPy)、op(通用 ML);
  • "graph" 一词有歧义:要明确指的是 CUDA graph、autograd graph 还是 capture graph。

受众校准:写给 Python 用户,不写给原生开发者

Warp 发布说明的受众是"从 Python 使用 Warp 的人"。他们看到 @wp.kernel、wp.tile_load、wp.array、storage= 参数;他们不读 warp/native/*.h,不了解 CUDA 硬件模型,看不出 RTDyld 与 JITLink 的区别,也不写 PTX。

如果一句话只有读 warp/native/*.h 的人才懂,就要改写。需要翻译或删除的 GPU/CUDA 内部内容:

  • float4 向量化、合并访问、warp 内存合并、bank 冲突、分散访问模式、stride-1 访问;
  • PTX 内建函数、fma.rn.bf16、fence 指令;
  • RTDyld、JITLink、CPU JIT 链接器内部机制。

当变更的头条价值是性能收益时,先说用户可见的影响("在 Y 负载上快 X%"或"kernel 从 18s 编译降到 1s"),略去机制;当机制本身用户可见时,用用户能懂的语言描述("按行而非按列读取"、"跳过慢速 LTO 编译步骤"、"留在寄存器内存而不经全局内存往返")。不要暴露用户无法行动的 CUDA 原语。

其他不允许进入发布说明的内部术语:

  • 技能内部名称("Phase 5b"、"headline counts"、"{{PLACEHOLDER}}");
  • 内部 Python 模块路径(warp._src.*),改用公共表面(@wp.kernel、wp.tile_load);
  • C++/CUDA 内部类型名(launch_bounds_t、tile_register_t、wp_array_t);
  • 提交 SHA、分支名、内部 jira ID、审计工具标志。

CHANGELOG 改写:从"评审者视角"到"用户视角"

CHANGELOG 写给懂内部的代码评审者,发布说明写给只接触公共 warp API 的 Python 用户。逐字搬运 CHANGELOG 条目几乎总是错的。 把每条 bullet 当作起点,然后:

  1. 识别技术行话("bank conflicts"、"vectorized path"、"coalesced byte-copy"、"LTO"、"fp32 round-trip"、"rank cap"、"register spills"),按上述规则为 Python 用户受众改写;
  2. 拉取关联的 GitHub issue 或 MR(gh issue view <NNNN> / gh pr view <NNNN>),看动机、基准数字与场景描述。用户可见的表述("该场景在 2 的幂 tile 尺寸下慢 X%"、"该工作流此前需要变通方案")通常存在于那里,而不在压缩给工程师看的 CHANGELOG 条目里;
  3. 用源码交叉核对任何实现声明。CHANGELOG 说"使用原生 bf16 内建函数",就验证该路径在目标架构上确实被走通;说"现在支持 N >= 2 的 N-D",就检查旧形态已支持什么。"Supports N-D"可能指全新能力,也可能只是解除 rank 上限,用户侧表述截然不同;
  4. 把"improved memory access patterns"、"high-rank tile traffic"、"follows correct semantics"翻译成具体的用户可见收益,否则删除该声明(见下节"拒绝空泛声明")。

拒绝空泛声明

声称行为"正确"、"符合预期"、"兼容"、"正常工作"、"遵循正确模式"却不点名场景的句子是空泛的,不值得占位。要么:

  • 具体化:点名其发挥作用的场景("在 wp.capture_begin() 图捕获内工作"、"与 RMM 的 CudaAsyncMemoryResource 语义一致"、"与 PyTorch 的 RMM 后端分配器集成");
  • 或删除该句。

检验标准:如果读者把句子替换成 <合理的事情发生了> 而不丢失任何信息,该句就是空泛的,应删除。

每条技术声明都必须通过三个过滤器之一:

  1. 具名 API 或工作流的具体用户场景;
  2. 带单位的实测影响("1.2-1.7x faster"、"compiles in 1s instead of 18s"、"drops simulation time from 1.41s to 0.98s");
  3. 可链接的 issue / MR / 文档,提供完整细节。

前瞻性声明:必须要有主源支撑

发布说明是公开承诺。任何前瞻性声明("will land in vX.Y"、"scheduled for"、"slated for"、"next release"、"soon")都必须由明确承诺该时间表的主源支撑:

  • 点名移除版本的 CHANGELOG ### Deprecated 条目;
  • 源码中运行时 DeprecationWarning 的发射字符串;
  • 被弃用符号或特性的 docstring;
  • 带明确版本承诺的设计文档或跟踪 issue;
  • 维护者在 issue/MR 上的明确陈述。

弃用政策("至少 4 个月 / 4 个特性版本")是下限而非时间表。把最早合法版本当作发布计划来写,等于做出项目必须兑现的隐性承诺。该政策的源码级佐证见 docs/user_guide/compatibility.rst:被弃用特性通常在弃用宣布后至少维护 4 个月,按月度特性发布节奏,这相当于约 4 个特性版本。

没有主源时使用中性表述:

  • "...will be removed in a future feature release per the standard deprecation timeline."(适当时链接 compatibility.html);
  • "...tracked in #NNNN"(存在开放跟踪项时);
  • "...designed-but-deferred"(用于"无立即行动"分类的跟踪项)。

引用跟踪 issue 时要读 issue 结构:许多 issue 区分"Closes known gaps"/"Diagnostics"/"Architectural"(积极跟踪中)与"Designed but not implemented anywhere, no immediate action required"(已推迟)。不要把推迟区条目提升为"tracked"状态。

对发布节奏与流程声明,使用期望性语言("Warp aims to publish a feature release every month")而非断言式("Warp now publishes...")。读起来像永久承诺的节奏声明会把团队锁死。

Announcements 小节写法

公告用第二人称撰写("Update to Python 3.10 or newer to continue receiving Warp updates"),并以用户可见影响开头。bullet 形态:

- **Python 3.9 is no longer supported.** Python 3.10 is now the minimum
  required version. Update to Python 3.10 or newer to continue receiving Warp
  updates.

前导子句加粗,其余为普通散文。每个 bullet 回答三个问题:什么变了、何时变、用户该怎么办。

对于本版本已实际落地的弃用(警告现在触发、移除稍后到来),陈述当前状态并按弃用政策指路,不臆造版本号:Deprecated in 1.13; will be removed in a future feature release per the standard deprecation timeline. 只有主源承诺了具体移除版本才点名(见上文"前瞻性声明")。

移除与弃用的语气

移除/弃用 bullet 必须:

  • 以事实陈述变更(加粗前导子句);
  • 给出与用户结果挂钩的中性迁移步骤;
  • 避免就过往弃用周期说教或"我早告诉过你"的口吻。

❌ 反面(尖刻、责怪用户未迁移):

- **Python 3.9 is no longer supported.** Python 3.10 is now required. If you
  saw the deprecation warning in v1.12, the time to upgrade is now.

✅ 正面(中性、与行动挂钩):

- **Python 3.9 is no longer supported.** Python 3.10 is now the minimum
  required version. Update to Python 3.10 or newer to continue receiving Warp
  updates.

只有在前序背景承载信息时才提,例如"finalizing the deprecation announced in v1.11",而不是作为对未迁移用户的喊话。

Acknowledgments 与页脚

致谢小节

以标准行开头:

We also thank the following contributors from outside the core Warp development team:

每个 bullet:

- @username for [specific contribution] (#NNNN).

贡献描述要具体。"for fixing the inverted verbose flag in wp.capture_debug_dot_print()"优于"for a bugfix"。读者可能是贡献者未来的雇主或同行,这一行应如实反映他们实际做了什么。

贡献者有多个 PR 时,可以合并成一个带多个 #NNNN 引用的 bullet(若贡献不相关则列多个独立 bullet),自行判断。

配套的 .codex/skills/warp-release-notes/references/contributor-attribution.md 定义了贡献者归属的判定规则(cherry-pick 过滤、CHANGELOG 分区归属、外部/NVIDIA 分类阈值等),style-rules 中的致谢格式需要与其配合使用。

页脚

文档以水平规则加一行指向完整 changelog 的提示结尾:

---

For a complete list of changes, see the [full changelog](https://github.com/NVIDIA/warp/blob/v<version>/CHANGELOG.md).

对于 bugfix 版本,changelog 指针可以替代正文的大半内容——用户已认可"see the full changelog for details"可作为 bugfix 版本的主导叙述。不要逐条复制 changelog 的每个修复 bullet。

与发布说明模板的配合

style-rules 不是孤立文档,它与 .codex/skills/warp-release-notes/references/feature-release-template.md(特性版本 X.Y.0)配合使用:模板定义了 ## New features(主特性块、实验告示、Key capabilities、跨语言消费侧代码、产物块)、主题分组、破坏性变更、Bug fixes(默认省略,只有满足"静默语义偏移、改变用户可观察行为、消除社区反复踩的坑"三类标准之一且有 2 个以上修复才保留)、## Announcements 与 ## Acknowledgments 的占位结构,而 style-rules 则为填充这些占位提供每条硬约束。技能流程(.codex/skills/warp-release-notes/SKILL.md)在 Phase 4 规划分组与 Phase 5 起草阶段会重读这两份参考,Phase 5e 的自审清单要求逐条核对 style-rules 是否全部应用——每一条未应用的规则,都是发布经理将要额外消耗的一轮迭代。

结语

将这份规范应用于当前仓库可以立即看到成效:为下一个版本(当前 VERSION.md 为 1.19.0.dev0,CHANGELOG 最新发布为 1.18.0)起草发布说明时,用 #NNNN 纯引用、GFM 告示块标注 **Experimental** 条目、按"解锁能力优先"组织每个特性段落、为每个新 API 配真实运行过的代码示例,并按"主特性 → 主题分组 → 性能 → 公告 → 致谢"排序,即可产出一份既对 Python 用户友好、又经得起源码与测试验证的发布说明。这套规则同样适用于任何希望为开源项目撰写高质量、可检索、可引用发布文档的团队。


登录后查看全文
warp