StarFive Linux内核补丁提交指南：从代码修改到合入主线的完整流程

前言

在开源社区贡献代码是许多开发者的目标，而向Linux内核提交补丁更是一项具有挑战性的工作。本文将以StarFive项目为例，详细讲解如何规范地向Linux内核提交补丁，提高代码被接受的概率。

准备工作

获取最新源码树

在开始修改前，你需要获取最新的内核源码。推荐使用Git进行管理：

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

但需要注意，大多数子系统维护者都有自己的开发树，你应该基于这些树进行开发。可以通过MAINTAINERS文件查找对应子系统的维护者信息。

开发环境配置

建议配置Git以优化补丁提交体验：

[core]
    abbrev = 12
[pretty]
    fixes = Fixes: %h (\"%s\")

编写高质量的补丁描述

问题描述

每个补丁都必须清楚地描述它要解决的问题：

• 说明问题的严重性（崩溃、性能下降等）
• 提供可重现的步骤或日志片段
• 量化优化效果（性能提升百分比等）

技术细节

用简洁的技术语言描述你的修改方案：

• 使用祈使语气（如"修复XYZ问题"而非"我修复了XYZ问题"）
• 避免依赖外部资源，关键讨论要点应包含在描述中
• 对于复杂修改，说明设计决策和权衡考虑

引用规范

当引用其他提交时：

• 使用完整的12字符SHA-1 ID
• 包含提交的摘要信息
• 示例：

Commit e21d2170f36602 ("video: remove unnecessary platform_set_drvdata()")

特殊标记

• Link: 标记相关讨论链接
• Closes: 标记修复的问题（使用公开可访问的URL）
• Fixes: 标记修复的具体提交

补丁组织规范

单一职责原则

每个补丁应该只解决一个问题：

• 将bug修复和功能增强分开
• API变更和使用新API的驱动分开
• 但单个逻辑变更涉及多个文件应放在一个补丁中

依赖关系

如果补丁有依赖：

• 在描述中明确说明"本补丁依赖补丁X"
• 确保每个补丁提交后内核仍能正常编译运行

提交规模

建议每次提交15个左右补丁，等待评审后再继续：

• 大规模修改应分批次提交
• 每批补丁应保持内核可构建和运行

代码风格检查

基本规范

• 遵循Documentation/process/coding-style.rst
• 使用scripts/checkpatch.pl检查
• 特别注意：
  • ERROR级别必须修复
  • WARNING级别需要仔细评估
  • CHECK级别建议考虑

特殊情况

移动代码时：

• 移动操作和修改操作应分开提交
• 先提交纯移动的补丁
• 再提交修改的补丁

提交流程

收件人选择

• 使用scripts/get_maintainer.pl确定相关维护者
• 默认抄送[e-mail]
• 安全补丁发送至[e-mail]
• 影响用户空间的变更通知man-pages维护者

提交格式要求

• 必须以内联文本形式提交
• 禁止MIME附件或压缩包
• 推荐使用git send-email
• 邮件客户端需正确配置以防破坏补丁格式

邮件标题规范

• 必须包含[PATCH]前缀
• 后续版本使用[PATCH v2]等形式
• 重发未修改补丁使用[PATCH RESEND]

开发者证书

每个补丁必须包含签名行，格式为：

Signed-off-by: 姓名 <邮箱>

签名表示你确认：

1. 代码是本人编写或有合法权利贡献
2. 允许按开源许可证分发
3. 理解实际修改会被跟踪

评审与跟进

回应评审意见

• 礼貌回应所有评论
• 明确说明你做了哪些修改
• 感谢评审者的时间
• 新版本需说明与上一版的差异

邮件讨论规范

• 使用交错式回复（非顶部回复）
• 适当修剪引用内容
• 保持专业和耐心

后续跟进

• 通常2-3周内会收到回复
• 至少等待1周后再提醒
• 合并窗口期可能更慢
• 重发未修改补丁需添加RESEND标记

总结

向StarFive Linux内核提交补丁是一个需要耐心和细心的过程。遵循这些规范不仅能提高补丁被接受的概率，也是对其他开发者时间的尊重。记住，内核开发是协作过程，良好的沟通与规范的流程同样重要。