Warp 发布说明风格规范全解析:从 `NNNN` 引用到可运行代码示例的成文准则
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 原语家族"聚合正是发布说明的应有形态。
按影响力排序
每个发布内,小节大致按以下顺序:
- 主特性——值得在
## New features顶部拥有独立## …块的一两个条目; - 其他新特性与主题分组(tile、JAX、fem 等);
- 性能改进(如果幅度可观);
- 语言增强 / 编译工具链;
- 新示例(如有值得提的);
- Bug 修复(仅限值得单独强调的;CHANGELOG 已收录全部);
- 公告(弃用、平台支持);
- 致谢。
主特性由用户在范围确认时指定,或由技能作者从 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 分钟;把坏片段发进已发布的发布说明,代价是信誉。
对每个片段的标准流程:
- 将片段原样保存到
/tmp/release_notes_example_<short-name>.py; - 在仓库根目录用
uv run /tmp/release_notes_example_<short-name>.py运行,完整捕获 stdout; - 把捕获到的输出嵌入发布说明(单行 → 行尾
#注释;多行/结构化 → 独立 ```text 块); - 完成后删除临时文件。
片段跑失败就修片段(是片段有 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 当作起点,然后:
- 识别技术行话("bank conflicts"、"vectorized path"、"coalesced byte-copy"、"LTO"、"fp32 round-trip"、"rank cap"、"register spills"),按上述规则为 Python 用户受众改写;
- 拉取关联的 GitHub issue 或 MR(
gh issue view <NNNN>/gh pr view <NNNN>),看动机、基准数字与场景描述。用户可见的表述("该场景在 2 的幂 tile 尺寸下慢 X%"、"该工作流此前需要变通方案")通常存在于那里,而不在压缩给工程师看的 CHANGELOG 条目里; - 用源码交叉核对任何实现声明。CHANGELOG 说"使用原生 bf16 内建函数",就验证该路径在目标架构上确实被走通;说"现在支持 N >= 2 的 N-D",就检查旧形态已支持什么。"Supports N-D"可能指全新能力,也可能只是解除 rank 上限,用户侧表述截然不同;
- 把"improved memory access patterns"、"high-rank tile traffic"、"follows correct semantics"翻译成具体的用户可见收益,否则删除该声明(见下节"拒绝空泛声明")。
拒绝空泛声明
声称行为"正确"、"符合预期"、"兼容"、"正常工作"、"遵循正确模式"却不点名场景的句子是空泛的,不值得占位。要么:
- 具体化:点名其发挥作用的场景("在
wp.capture_begin()图捕获内工作"、"与 RMM 的CudaAsyncMemoryResource语义一致"、"与 PyTorch 的 RMM 后端分配器集成"); - 或删除该句。
检验标准:如果读者把句子替换成 <合理的事情发生了> 而不丢失任何信息,该句就是空泛的,应删除。
每条技术声明都必须通过三个过滤器之一:
- 具名 API 或工作流的具体用户场景;
- 带单位的实测影响("1.2-1.7x faster"、"compiles in 1s instead of 18s"、"drops simulation time from 1.41s to 0.98s");
- 可链接的 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 用户友好、又经得起源码与测试验证的发布说明。这套规则同样适用于任何希望为开源项目撰写高质量、可检索、可引用发布文档的团队。