Warp 发布说明编写规范:从 `NNNN` 引用到可运行代码示例的完整指南
Warp 发布说明编写规范:从 #NNNN 引用到可运行代码示例的完整指南
本篇指南以 NVIDIA Warp 开源仓库中 .claude/skills/warp-release-notes/references/style-rules.md 为骨架,系统讲解 Warp 发布说明(release notes)的硬性写作约束:GitHub 引用格式、GFM 提示块、实验特性标记、代码示例与输出渲染、before/after 迁移片段、语言与文体规范等。读者读完可以独立产出一份符合 Warp 社区审阅标准、面向 Python 用户、可复制可运行的发布说明,并能将其与仓库现有的 Towncrier changelog 片段工作流(changelog/ 目录与 design/towncrier-changelog-fragments.md)无缝衔接。
文档定位:一份约束"渲染结果"的写作规范
style-rules.md 是 warp-release-notes skill 的核心参考文件之一,它定义的约束是硬性的("These are the hard constraints"),要求在发布说明撰写流程的收尾阶段(原文中的 Phase 6)严格执行。这些规则并非凭空而来,而是总结自 Warp 已发布的 v1.10 至 v1.12.1 版本说明,并叠加了 skill 采集的用户偏好。
该 skill 的完整文件集位于 .claude/skills/warp-release-notes/,与本文档配套的还包括:
- SKILL.md:skill 主流程定义;
- references/feature-release-template.md:功能版本(X.Y.0)的成文模板;
- references/bugfix-release-template.md:bugfix 版本的成文模板;
- references/feature-investigation.md:动笔前对每个特性做源码级调查的协议;
- references/contributor-attribution.md:致谢名单的核实方式。
其中模板文件大量引用本文档的规则,例如 feature-release-template.md 明确要求"每个 breaking change 小节必须携带 before/after 代码片段,而非散文,形状见 style-rules.md"。因此,可以把 style-rules.md 理解为整套发布说明生产线的渲染与文风宪法。
GitHub issue / PR 引用:发布说明只用 #NNNN
第一条硬性规则是关于 issue / PR 引用的形式:
使用纯
#NNNN,绝不要用[GH-NNNN](https://github.com/NVIDIA/warp/issues/NNNN)。
原因在于发布说明总是发布在同一个 GitHub 仓库上,GitHub 会自动把 #NNNN 解析为可点击链接,并在悬停时显示 issue / PR 标题。带完整 URL 的 GH-NNNN 形式更适合 CHANGELOG.md(它需要在 GitHub 之外的环境也能消费),但放在发布说明里会显得笨重。
- ✅ 正确:
Fix kernel cache serving stale binaries when compilation settings change (#903). - ❌ 错误:
Fix kernel cache serving stale binaries when compilation settings change (GH-903).
当一条 bullet 覆盖多个 issue 时,用逗号分隔、每个都带 #:
- ✅ 正确:
Tile programming gains new primitives (#1287, #1298, #1342, #1364).
仓库里的实际数据正好印证了这两种形式的分工:仓库根目录的 CHANGELOG.md 中的条目全部使用 GH-NNNN 完整链接形式(例如 1.18.0 的 Add the warp.geometry module ... ([GH-1797](https://github.com/NVIDIA/warp/issues/1797))),供非 GitHub 环境消费;而 changelog/ 目录下的 Towncrier 片段文件(如 changelog/2038.added.md、changelog/1781.fixed.md)正文中不写任何链接,issue 链接由 Towncrier 渲染时自动追加,这与 design/towncrier-changelog-fragments.md 中"contributors do not put that link in the fragment text"的要求一致。
提示块:只用 GFM Admonitions
需要视觉分离的信息,使用 GitHub Flavored Markdown 的 alert 块,五种规范形式:
> [!NOTE] — useful background even when skimming
> [!TIP] — helpful advice for doing things better or more easily
> [!IMPORTANT] — key information users need to achieve their goal
> [!WARNING] — urgent info needing immediate attention to avoid problems
> [!CAUTION] — risks or negative outcomes of certain actions
在 github.com 上,每种形式都会渲染出带彩色图标和标签的块。禁止使用自创形式:
- ❌
> **Note:** Useful background... - ❌
**Note:** Useful background... - ❌
> _Note:_ Useful background... - ❌
> ⚠️ Warning: ...(应改用> [!WARNING])
类型要按意图选择,而不是按 emoji 偏好:[!IMPORTANT] 用于用户成功所需的关键信息(实验状态、破坏性变更的迁移路径);[!NOTE] 用于附带背景;[!CAUTION] 用于读者可以规避的风险;[!WARNING] 用于置之不理就会出错的事项。整篇发布说明中提示块控制在 1 至 2 个,且不能连续堆叠两个。
实验特性:标记放在每个具体的 ### 块下
当某个 ### … 块描述的功能,其 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。
仓库中 CHANGELOG 的实际条目可以对照参考,例如 1.18.0 中"Experimental: Add cooperative CPU block execution for explicit block_dim values ..."这类带 Experimental 前缀的条目,正是发布说明中需要套用上述提示块形状的信号。
内容组织:以"解锁"开头,按主题分组,按影响力排序
第一句回答"现在能做什么以前不能做的事"
每条功能描述的第一句话都应回答:现在有什么是以前做不到的? 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 原语归 Tile,JAX 特性归 JAX,warp.fem 特性归 warp.fem。即使 CHANGELOG 把它们列为带不同 GH 引用号的独立条目,发布说明也要分组。分组的依据是用户如何思考功能("我在做 tile 相关的工作"),而不是代码库如何组织它们。
- ✅ 正确:单一主题小节
## New tile primitives下列出wp.tile_dot()(#1364)、wp.tile_axpy(alpha, src, dest)(#1363)、wp.tile_scatter_add()(#1342) 和wp.tile_scatter_masked()(#1298); - ❌ 错误:为每一个 tile 原语各开一个
## ...小节。
这些原语在源码中都有对应实现,例如 warp/init.pyi 中的 tile_dot(第 5793 行)、tile_axpy(第 5836 行)、tile_scatter_add(第 5441 行)、tile_scatter_masked(第 5550 行),写作时可以先核对签名再下笔。
章节按影响力排序
每个版本内部,章节大致按以下顺序出现:
- 头条特性(值得在
## New features顶部独占## …块的 1 至 2 项); - 其他新特性与主题组(tile、JAX、fem 等);
- 性能改进(如足够突出);
- 语言增强 / 编译工具链;
- 新示例(如有值得提的);
- Bug 修复(仅在值得强调时,完整清单在 changelog 里);
- 公告(弃用、平台支持);
- 致谢。
头条特性由用户在范围确认阶段指定,或由 skill 作者从 CHANGELOG 中判断最激动人心的条目。例如对 1.13 版本而言是 APIC graph capture serialization with CPU graph replay。feature-release-template.md 的注释也明确要求按用户影响力排序,而非按 changelog 顺序。
标题规范
章节标题(## …、### …)要短、有描述性、用主动语态。它们不是完整句子:不加句号,不用整段散文。
- ✅
### Graph capture serialization and CPU replay - ❌
### Adding graph capture serialization with CPU replay support.
特性块内部的子标题(如"Key capabilities")用加粗段落标签 + 冒号,而不是自己的 #### 标题:
- ✅
**Key capabilities:**后跟 bullet 列表; - ❌
#### Key capabilities。
代码示例:默认,而不是例外
每个 ### … 块都要带可运行示例
代码示例是默认配置,不是例外。 每个描述新公开 API 或行为变更的 ### … 块,都要附带一段可运行的 Python 代码,展示最简单的有意义用法:
- 顶部放 import(
import warp as wp等); - 不调用
wp.init()。Warp 在首次使用时隐式初始化,在示例中调用wp.init()是过时写法,即使旧版发布说明里有也要删掉; - 一段简短的内核或调用序列;
- 展示程序输出(见下方"输出渲染");
- 示例必须是能跑的代码,不是伪代码,长度目标 5 至 15 行。
输出渲染:单行注释与独立 text 块
程序输出按长度和结构选择两种形状之一:
-
单个短值 → 行尾
#注释,直接写在print(...)行上:print(out.numpy()[:8]) # [0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5] -
多行或结构化输出 → 独立的
text代码块,紧跟 Python 块之后,用一行说明文字引出("Output:"、"Prints:"、"Result:"),中间空一行。适用于表格、多行 dump、命名分节报告等需要纵向扫读的输出。把多行输出埋在# 注释里会掩盖特性的实际价值: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)
阈值判断:输出只有一行 → 用内联注释;输出跨 2 行以上、或有内部结构(行、表、key:value、嵌套缩进)→ 用独立 text 块。读者永远不应该需要在脑中重新格式化一段 # 注释 才能理解打印结果。
对于"输出本身就是特性卖点"的场景,输出渲染不可商量:
wp.ScopedMemoryTracker/wp.config.track_memory:作用域退出时打印的分配汇总表本身就是特性的头条价值,必须在独立块中展示真实表格;wp.print_diagnostics():格式化的环境 dump 就是全部意义,必须在text块中渲染;- bfloat16 / fp64 提升:短小的 dtype 确认可以用行尾注释形式;
- 近似数学内建函数:并排的数值差值短到可以内联;多行精度表放进
text块。
这些 API 都能在源码中找到落点:ScopedMemoryTracker 定义于 warp/_src/utils.py 第 2304 行,track_memory 配置开关定义于 warp/config.py 第 338 行,print_diagnostics 定义于 warp/_src/context.py 第 16385 行,仓库还提供了完整演示 warp/examples/core/example_alloc_tracker.py。
每个示例都必须端到端运行验证
发布说明中的每个可运行 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.* 路径;手工输入与真实渲染不符的预期输出。
如果运行不现实,优先把片段改成可运行的(提供最小输入),而不是在旁边加注解。实在不行才给 API-shape 片段加头部注释说明(例如 # API-shape example; requires a CUDA context),避免读者复制粘贴后直接跑;对于 C++ / 跨语言消费端片段,按 .claude/skills/warp-release-notes/references/feature-investigation.md 中"Cross-language requirements"的省略与签名核对协议处理。如果某片段需要运行但无法运行(构建未更新、依赖缺失、GPU-only 测试环境),要把失败如实反馈给用户,而不是伪造输出。
唯一可以合法纯文字叙述的条目是:单参数整理、单开关切换、无 API 变化的纯性能优化。拿不准就加片段。过去的评审反复把"这一节全是 bullet 没有代码"列为头号抱怨,默认给片段就是解药。
对于分组多个相关新 API 的小节(如"New tile primitives"),每个命名 API 各配一个自己的短片段,而不是合并成一个综合 dump。多个片段可以共享一个 setup,但每个新符号的调用点都要原样展示。
跨语言与跨运行时特性:两侧都要有示例
任何跨越语言或运行时边界的特性,都必须在每一侧附带片段,而不只是 Python 编写侧:
- Python → 独立 C++(例如 graph capture serialization):一个 Python
…_save片段 + 一个最小 C++ 消费端片段(头文件、初始化顺序、load + replay 调用)。如果仓库内 warp/examples/cpp/ 下已有可用示例,要链接到对应发布 tag 的仓库相对路径; - Python → JAX:一段 Python 内核定义 + 一个
jax_kernel(...)绑定,展示消费端的导入与调用模式。JAX 侧绑定在源码中对应 warp/_src/jax/ffi.py 的jax_callable(第 1746 行)等公开入口; - Python → PyTorch / DLPack:一个展示往返的片段(消费端用
wp.from_torch/__dlpack__)。from_torch定义于 warp/_src/torch.py 第 189 行。
命名消费端的头文件或导入路径不是可选项。 只看到生产端的读者无法判断该特性是否解决他们的问题。
当消费端示例必须省略样板代码(超过 50 行:遍历模块目录、加载 object 文件、注册内核符号、建立 CUDA context)时,必须同时做到:逐一核对片段中每个 API 调用签名与对应头文件一致;在散文里明确说明省略了什么;在代码中省略处放内联占位注释;链接完整的仓库内示例(按发布 tag 路径,不用 main、不用 SHA)。
破坏性变更: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 片段消除了猜测。retain_grad 参数在源码中有真实支撑(见 warp/_src/context.py 第 9948 行附近的 wp.zeros / empty_like 定义),可以作为核对对象。
按变更形态选择围栏语言:
-
迁移跨多行、需要新 setup、或体现行为转变时(如
.grad读取现在归零、默认值变化、输出现在需要retain_grad=True),用两个python块,各自带# v1.X behavior:/# v1.Y migration:注释头,承载 import、作用域和完整调用上下文; -
变化是紧凑的签名迁移、参数改名或单行调用点更新时,用单个
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 着色(只有前导 +/- 上色),长迁移代码读起来更差。
产物与示例链接
描述特性产出的磁盘产物
当特性写出新的磁盘产物(文件格式、序列化图、检查点)时,要描述超出表面文件之外的内容。sidecar 目录、版本锁定的二进制、架构锁定的 CUBIN 是常见坑:用户只带 name.wrp 而不带 name_modules/ 目录,会遇到静默加载失败。产物不止一个文件时,用字面目录树代码块:
scene.wrp # operation byte stream + region snapshots + metadata
scene_modules/
abc123.cubin / .meta # one per kernel module, arch-pinned
链接仓库内示例
特性在 warp/examples/** 下有可用示例时,要显式链接,使用发布 tag 对应的仓库相对路径(不用 SHA、不用 main,因为文件可能移动)。如果链接会指向 tag 上已移动或不存在、不存在的文件,就删掉它。对于跨语言特性(如 APIC 图序列化的 C++ 消费端),仓库在 warp/examples/cpp/ 下有 00_cubin_launch、01_source_include、02_apic_visualization 等示例目录,写作时应优先链接这些真实存在的入口,而不是让读者自己去 grep 仓库。
语言与文体
专有名词大小写
始终大写:NumPy、Warp、NVIDIA、CUDA、JAX、PyTorch、Python、OpenGL、Linux、Windows、macOS、Apple Silicon、ARM64、x86_64。散文中绝不小写;唯一的例外是代码中引用的字面符号(反引号内的 numpy.float32 没问题)。
标点
-
正文禁用 em dash(
—)。用逗号、句号或冒号替代:- ❌
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 / 数组参数注解使用下标式:
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 等静态类型检查器会把它标记为构造函数调用。发布说明片段应使用现代形式。对 C++ / CUDA 片段,则要匹配仓库内对应特性的示例所用的注释与结构约定。
Warp 词汇
使用 Warp 自己的术语,不要借用其他框架的词:
- ✅ tile、array、kernel、struct、builtin(Warp);
- ❌ tensor(PyTorch)、ufunc(NumPy)、op(通用 ML)。
"graph"一词过载:要明确区分 CUDA graph、autograd graph、capture graph。
受众:Python 用户,而非 native 开发者
发布说明的受众是"从 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 链接器内部。
当变更的头条价值是性能时,以用户可见影响开头("X% faster on Y workload"或"kernel compiles in 1s instead of 18s"),省略机制;当机制本身用户可见时,用用户能懂的语言描述("按行读取而非按列"、"跳过了慢速 LTO 编译步骤"、"留在寄存器内存中而不是经过全局内存往返")。不要暴露用户无法操作的 CUDA 原语。
其他不应出现在发布说明中的内部术语:
- skill 内部名称("Phase 5b"、"headline counts"、
{{PLACEHOLDER}}); - 内部 Python 模块路径(
warp._src.*),改用公开面(@wp.kernel、wp.tile_load); - C++ / CUDA 内部类型名(
launch_bounds_t、tile_register_t、wp_array_t); - commit SHA、分支名、内部 JIRA ID、审计工具标志。
如果 CHANGELOG 或 docstring 用了这些术语,在搬进发布说明前先改写(见下节)。
CHANGELOG 改写:逐字照搬几乎总是错的
CHANGELOG 是写给懂内部原理的代码评审者看的;发布说明是写给只与公开 warp API 打交道的 Python 用户看的。把 CHANGELOG bullet 原样搬进发布说明几乎总是错的。 把每条 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%"、"这个工作流之前需要 workaround")通常存在于那里,而不是在已经为工程师压缩过的 CHANGELOG bullet 里; - 用源码交叉验证任何实现声明。CHANGELOG 说"uses native bf16 intrinsics",就要验证相关架构上确实走了该路径(见 feature-investigation.md 的"Verify symbol references");说"now supports N-D for N >= 2",就要查旧形式本来支持什么,"支持 N-D"可能意味着全新能力,也可能只是解除 rank 上限,用户可见的框架截然不同;
- 把"improved memory access patterns"/"high-rank tile traffic"/"follows correct semantics"翻译成具体的用户可见收益,或者删掉该声明(见"拒绝模糊声明")。
仓库中 changelog/ 目录下的片段就是很好的改写参照:例如 changelog/2038.added.md 直接面向用户描述 NumPy dtype 互操作行为("avoiding object arrays"、"Use wp.dtype_to_numpy() with older NumPy versions"),changelog/1781.fixed.md 精确指出修复的 API 与受影响平台,都没有内部实现细节。
拒绝模糊声明
声称行为"correct"、"as expected"、"compatible"、"works properly"或"follows the right pattern"却不说场景的句子,是空话,不值得占据篇幅。二选一:
- 说具体:点名相关场景("works inside
wp.capture_begin()graph capture"、"matches RMM'sCudaAsyncMemoryResourcesemantics"、"integrates with PyTorch's RMM-backed allocator"); - 或删掉。
测试方法:如果读者可以把句子替换成 <reasonable thing happens> 而不丢失任何信息,这句就是空话,应该删。每条技术声明都要通过三个过滤器之一:
- 具名 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中具名移除版本的 bullet; - 源码中运行时
DeprecationWarning的 emit 字符串; - 被弃用符号或特性的 docstring;
- 明确承诺版本的设计文档或 tracker issue;
- 维护者在 issue/MR 上的明确声明。
弃用政策("至少 4 个月 / 4 个 feature release")是底线,不是时间表。挑最早合法版本并把它说成发布计划,等于替项目做了一个不得不守的承诺。
没有主来源时,用中性框架:
- "...will be removed in a future feature release per the standard deprecation timeline."(适当时链接仓库中的兼容性文档);
- "...tracked in #NNNN"(存在开放 tracker 时);
- "...designed-but-deferred"(针对"no immediate action"分节的 tracker 项)。
引用 tracker 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、Acknowledgments 与 Footer
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 必须:把变更作为事实陈述(开头分句加粗);给出与用户结果挂钩的中性迁移步骤;避免指责用户没迁移的"我早说过"式口吻。只有迁移信息本身是关键时(如"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,要么在贡献互不相关时分开列,酌情处理。
Footer
文档以水平分割线结尾,加一行指向完整 changelog 的说明,在仓库内即指向 CHANGELOG.md:
---
For a complete list of changes, see the <a href="https://link.gitcode.com/i/c5240d7a04790c6b85cd7d0b39cfdf8a" target="_blank">full changelog</a>.
对 bugfix 版本,changelog 指针可以替代大部分正文,因为用户已经说过"详情见完整 changelog"可以作为 bugfix 版本的主导叙述;不要重复 changelog 中的每一条修复 bullet。
与仓库发布工作流的衔接
style-rules.md 约束的是发布说明的渲染形态,而发布说明的内容素材来自仓库的 Towncrier 片段工作流,两者一起构成完整的发布链路:
- 贡献者在 changelog/ 下按
NNNN.<category>.md或+<slug>.<category>.md命名规则提交片段(类别顺序为 added、removed、deprecated、changed、fixed、documentation,见 changelog/README.md),片段正文是一个不以-开头的祈使现在时 bullet; - CI 以
uvx --from towncrier==25.8.0 towncrier build --draft --version Unreleased校验片段可渲染(见 design/towncrier-changelog-fragments.md),仓库现有片段如 changelog/1970.changed.md、changelog/2038.added.md 展示了实际文风; - 发布时运行真实版本的 towncrier build,把片段合并进 CHANGELOG.md;
- 撰写发布说明时,以 CHANGELOG 条目为素材,按本文档的引用格式、提示块、示例、before/after、文体规范重写为面向 Python 用户的成品。
本指南涵盖的正是第 4 步的全部规则,任何为 Warp 编写发布说明的人都可以把它当作可执行的检查清单:引用用 #NNNN、提示块只用 GFM 形式、实验特性加 [!IMPORTANT]、每节先讲"解锁价值"、代码示例必须真实运行过、breaking change 必须 before/after、内部术语一律改写。对照 CHANGELOG.md 和 changelog/ 的现有内容,即可快速校验最终稿与 Warp 社区既有文风的一致性。