维护者入门档案

维护者入门档案是对顶级过程文档(提交补丁、提交驱动程序...)的补充,其中包含了子系统/设备驱动程序的本地惯例以及补丁提交生命周期的详细信息。贡献者可以使用此文档来设定他们的预期并避免常见错误;维护者可以使用这些档案来跨子系统查找统一常见实践的机会。

概述

介绍子系统如何运作。虽然 MAINTAINERS 文件告诉贡献者应将补丁发送到哪些文件,但它不传达其他有助于开发的子系统本地基础设施和机制。

需要考虑的示例问题

  • 当补丁应用于本地树或合并到上游时,是否有通知?

  • 子系统是否有 patchwork 实例?patchwork 状态变化是否会通知?

  • 是否有任何监控列表的机器人或 CI 基础设施,或者子系统用于控制接受的自动化测试反馈?

  • 哪些 Git 分支会被拉入 -next?

  • 贡献者应该针对哪个分支提交?

  • 链接到任何其他维护者入门档案?例如,设备驱动程序可能会指向其父子系统的入门档案。这让贡献者了解维护者在提交链中可能对其他维护者承担的义务。

提交清单附录

除了常见的“提交清单”之外,列出补丁被维护者视为足够健康所需的强制性和建议性标准。例如:“通过 checkpatch.pl 检查,无错误或警告。通过 $URI 处详述的单元测试。”

提交清单附录还可以包含有关相关硬件规范状态的详细信息。例如,子系统是否要求在考虑补丁之前,已有特定修订版本的已发布规范。

关键周期日期

提交者常见的误解之一是,补丁可以在合并窗口关闭之前的任何时间发送,并且仍然可以被考虑用于下一个 -rc1。实际情况是,大多数补丁需要在合并窗口打开之前提前在 linux-next 中充分酝酿。为提交者明确关键日期(以 -rc 发布周为准),补丁何时可能被考虑合并,以及何时需要等待下一个 -rc。最低限度:

  • 新功能提交的最后 -rc:针对下一个合并窗口的新功能提交,应在此时间点之前首次发布以供考虑。在此时间点之后提交的补丁应明确说明它们的目标是 NEXT+1 合并窗口,或者应提供充分的理由说明为何应加快处理。一般指导原则是与贡献者设定预期,即新功能提交应在 -rc5 之前出现。

  • 合并功能的最后 -rc:合并决策的截止日期。告知贡献者何时尚未应用补丁集需要等待 NEXT+1 合并窗口。当然,没有任何义务必须接受任何给定的补丁集,但如果审查在此时间点尚未结束,则预期贡献者应等待并为下一个合并窗口重新提交。

可选

  • 开发基线分支(在概述部分列出)应被视为可接受新提交的第一个 -rc 版本。

审查节奏

贡献者最大的焦虑来源之一是,在补丁集发布后未收到任何反馈时,多久应该催促。除了指定重新提交前应等待多久之外,本节还可以指出首选的更新方式,例如重新发送完整系列,或私下发送提醒邮件。本节还可以列出此代码区域的审查工作方式,以及不直接来自维护者的获取反馈的方法。

现有档案

目前,现有的维护者档案列在此处;我们可能希望在不久的将来做些不同的事情。