今日重点:✍️ 写作——一封 4 句话的封面信,把「新增 UAPI + 三个驱动后续支持」 讲得明明白白。Niklas Söderlund 的 Bayer 20/24/28-bit 格式系列(3 帖) 是「UAPI 先行」型系列的写作范本:没有铺垫、没有客套,每句话都承担一个信息职能。

✍️ 真实原文:四句话的封面信

/ section
Hello, This series adds the pixel formats and documentation for the 20-, 24- and 28-bit Bayer formats. This is done in preparation of work on the Renesas R-Car video capture pipeline which will support these pixel formats in multiple drivers. For this reason it is posted as a separate series before the driver work.

逐句拆。第一句 This series adds the pixel formats and documentation for the 20-, 24- and 28-bit Bayer formats.——「本系列新增 XX」。动词 adds 后面跟两个宾语(pixel formats、documentation),一句话交代了补丁的两大块内容。 注意它没说「我为什么需要」,先讲清楚「是什么」,读者三秒进入状态。 第二句 This is done in preparation of work on the Renesas R-Car video capture pipeline which will support these pixel formats in multiple drivers.—— 用 This is done in preparation of work on ...(这是为……工作做准备)把动机锚定 在一个具体的下游工作上:R-Car 采集管线、多个驱动将使用这些格式。 比空泛的「随着高比特 sensor 普及」有力得多——评审能立刻判断影响面。

第三句 For this reason it is posted as a separate series before the driver work.——For this reason 回扣上一句的动机,it is posted as a separate series before the driver work 解释了为什么拆开发: UAPI 先定稿、驱动后跟进。这一句是整个模板的灵魂——它回答了评审必然要问的问题: 「为什么不和驱动一起发?」先答一步,评审就不用问了。

★ 阅读拆点 · 三个可复用句式

同 cover letter · 学会抓重点

This series adds X.(职责句) 系列的第一句永远先说「是什么」。adds 的宾语要把补丁的组成部分都露出来——本例把 documentation 和 pixel formats 并列,等于提前告诉评审「文档也在里面,别担心」。
This is done in preparation of work on Y.(动机句) in preparation of(为……做准备)把新接口与真实的下游工作挂钩。有具体下游的提案比抽象需求好过十倍:本例下游是 R-Car 采集管线,评审立即知道谁会受益。
For this reason it is posted as a separate series before ...(拆分辩护句) 「因此单独成系列、先于驱动」。当你的系列刻意拆开时(UAPI 先行、清理先行、测试先行),一定要在封面信里解释拆分理由,否则评审会当作不完整提案。
Hello,(极简开场) 就一个词。内核对封面信的开场白没有礼仪要求——直接进正文是常态,也是被欣赏的做法。少写一个「hope this email finds you well」,评审就少读一行。

✨ 辅助彩蛋(阅读)

/ column

★ 写作彩蛋 · diffstat 也是正文的一部分

同 cover letter · 文末统计

原文结构 3 个补丁按位深拆(20-bit / 24-bit / 28-bit),diffstat 总计 339 行插入:每个格式新增 103 行规格文档(pixfmt-srggb20/24/28.rst),外加 videodev2.h 的 12 行 fourcc 定义与 v4l2-core 的映射表改动。
可复用的检查表 UAPI 类系列的「完整」长什么样:① 文档(每格式一份规格)② 头文件(fourcc 常量)③ 核心映射(v4l2-common / v4l2-ioctl 的格式表)④ 与驱动工作分离的独立系列。四件套齐了,评审就知道这不是「顺手加个数字」。
为什么值得学 UAPI 一旦合入就不能随意改,所以「格式定义 + 文档」必须先在独立系列里定稿。这种「文档先行、驱动跟进」的节奏,是内核里最值得模仿的工程习惯之一。
和你相关 和你相关:哪天你要往 V4L2(或任何 UAPI)加自己的格式/ioctl,直接套这个结构:先发 UAPI + 文档,再发驱动。

✍️ 今日练习

/ column
✍️ 写作练习(英文作答):① 用「This series adds X. This is done in preparation of work on Y. For this reason it is posted as a separate series before Z.」三句模板,为你自己的一个改动写封面信开头(任何领域都行)。② 如果你的系列同时包含 UAPI 和驱动改动,为什么要拆开?用一句话英文说明。③ 本例 diffstat 里哪几个文件说明「文档先行」?
💡 显示答案
参考示例:① This series adds a new ioctl for runtime frame-rate configuration. This is done in preparation of work on the sensor bring-up which will need per-mode rates. For this reason it is posted as a separate series before the driver patches. ② Because the UAPI needs to be reviewed and frozen independently, so that driver work can proceed against a stable interface. ③ The three pixfmt-srggb20/24/28.rst documents (103 lines each) plus the pixfmt-bayer.rst index update.
📖 原文:This series adds the pixel formats and documentation for the 20-, 24- and 28-bit Bayer formats. This is done in preparation of work on the Renesas R-Car video capture pipeline which will support these pixel formats in multiple drivers. For this reason it is posted as a separate series before the driver work.
📎 原文引用

Four sentences, three jobs: say what it is, tie it to real work, justify the split.

素材:lore.kernel.org linux-media · Bayer 20/24/28-bit 格式系列封面信(Niklas Söderlund,〔11-16 03:11 北京〕,经 lore git 协议逐字提取)· 内核英语 · 每日一篇