LEDE如何提交补丁(代码)

翻译自 https://lede-project.org/submitting-patches 欢迎购买智能路由器开发指南(http://www.epubit.com.cn/book/details/4124

大部分开发项目组均有自己的代码提交规则,比如必须编译通过,并写提交注释,比如要符合某一代码风格,下面的是LEDE社区的代码提交规则, 可以供大家软件开发公司借鉴,适合开发团队较大,并且模块没有清晰划分的场景。 该提交规则和OpenWRT社区基本相同。也可参考http://openwrt.bjbook.net/howto.html

补丁可以在Github上通pull请求或通过邮件列表提交。

提交的内容应遵循以下原则:

  • 为每个pull请求使用不同的git分支(如果您通过网站编辑文件,GitHub会自动执行此操作)

  • 提交主题和消息写为:”add support for X”, 而不是 “added support for X”

  • 代码风格

    • 使用您正在修改的文件中相同的缩进,仅使用tab或仅使用空格,具体取决于你修改文件的其余部分
    • 列表中的条目应按字母顺序排列
  • 提交标题

    • 必须有一个前缀,前缀内容取决于您提交的内容
      • kernel: 用于内核和kmod(内核模块)软件包
      • package name: 针对软件包
      • device architecture: 用于设备(例如,mvebu:ramips:
      • tool name: 针对工具
      • build: 用于通用构建系统修改,不针对/toolchain中的某个东西
    • 必须小于50个字符长。
    • 必须描述提交变更以及为什么提交是必要的。\既简洁又具有描述性,这是一个具有挑战性的事情,但这是一个写得好的摘要应该要做的
    • 不要在前缀之后大写第一个字
    • 不要在标题的末尾写句号
  • 提交描述

    • 每行必须少于75个字符
    • 它会提交到源代码更新日志,所以它应该向有能力的读者解释为什么你做这个提交。 包括你正在修复的失败的症状(日志消息,错误消息等),这将是有用的,搜索提交日志的人员会查找到问题的修复程序代码。 如果修补程序修复了编译失败,则只包括编译失败日志中最相关的部分。
    • 如果添加对新硬件的支持:在提交消息中包含硬件简短描述以及如何在其上安装LEDE。
      有关一些示例,请查看[[https://git.lede-project.org/?p=source.git&a=search&h=HEAD&st=commit&s=add+support+for|recent additions]]。
  • 所有的提交必须包含’‘%%Signed-off-by: My Name <my@email.address>%%’’ 在那里写真实姓名和真实的电子邮件地址,

    依据 [[http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD#n416|Linux内核补丁指南第11节。]].

  • 它可以通过git命令行自动完成: ‘’git commit –signoff’‘

  • 作者字段必须匹配”Signed-off-by:” 行

    • 如果您编辑文件并通过GitHub提交,则必须在GitHub设置的“Name”字段中写入您的真实姓名,并且“Signed-off-by:”中使用的电子邮件必须
      是您的主要github电子邮件地址
    • 如果您正在编辑文件并在本地PC上提交,请使用
      git config –global user.name “my name” git config –global user.email “my@email.address”

使用Github

有一个开源的Github镜像[[https://github.com/lede-project/source|here]]。\ 使用Github Web界面将项目创建一个克隆,并将这个克隆下载到您的计算机,为您的更改创建一个分支,将其推回Github并提交pull请求。

如果你不知道该怎么做,继续阅读。\ 创建一个Github帐户,这将托管您的LEDE源的公共分支,并将用于Github上的所有交互。

在您的电脑中安装git,并确保您的本地git设置具有正确的名称和电子邮件

git config –global user.name “my name”

git config –global user.email “my@email.address”

您也可以将默认文本编辑器设置为您喜欢的编辑器(如果您有一个带有GUI的linux系统,那 geany, kwrite, pluma, gedit 是可能的选择。 如果你使用命令行,那 nano 是一个很好的选择) git config –global core.editor “editor-name-here”

然后跟随Github的非常好的文档 [[https://help.github.com/articles/fork-a-repo/|Fork A Repo]] 再接着[[https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork|创建一个本地克隆]]

在你按照描述设置以后,使用命令 git checkout -b my-new-branch-name 创建你合并请求的分支。 (“my-new-branch-name”仅仅是一个示例名称,使用一个更好自描述的名称。\ 在这个命令之后所有的提交将都在这个分支。 这允许你拥有多个分支,每一个PR一个分支。\ 在你已经创建的分支之间切换,使用 git checkout my-branch-name

在你做完修改,使用 git add -i 使用它的接口增加新的文件和更新已存在的文件。

然后使用 git commit –signoff 这将打开git默认的编辑器,然后你可以写提交信息。 第一行是提交标题,然后留一个空行再写提交描述信息。 这个命令将自动使用你上面设置的名字和邮件增加Signed-off-by行。

发送你的本地修改到Github仓库,使用 git push –all 在这个过程中将会问到github用户名和密码。

在代码更新到github仓库中,你可以通过Github Web接口提交PR(Pull request) 可以参考Github文档[[https://help.github.com/articles/creating-a-pull-request/|创建一个pull request请求]]\

通过邮件发送补丁

发送邮件到开发邮件列表[[https://lists.infradead.org/mailman/listinfo/lede-dev|development mailing list]]. 所有的补丁需要以与[[https://patchwork.ozlabs.org/project/lede/list/|patchwork]]中列出相同的格式来发送。 如果补丁没有被列入patchwork,那么它将不会得到处理。

强烈推荐使用 git send-email ,因为电子邮件客户端倾向于添加空格并拧紧格式,或添加不可打印的字符。

合并多个提交信息(Squashing commits)

通过PR来提交或者通过发送邮件,应该包含你所要合并的所有修改,而不是仅包含修复审阅者在您的原始PR中发现的所有问题

因此,您将需要重写或压缩您的提交,以便您以真实和正常的一次提交结束。

在你本地的git分支上使用git命令来操作

使用 git reset HEAD~X 删除提交(X是你想删除的提交数字,从上一次提交开始计数), 这个不更改文件,它仅仅删除提交。 再次增加文件到git跟踪库中使用 git add -i 再次使用 git commit –signoff 使用 git push -f 发送更新分支,PR中的提交自动更新。

另外一种简化提交信息的方法:

你可以使用rebase组合,重排序和编辑你的提交和他们的提交消息。

git rebase -i HEAD~X (X = 要编辑的提交数字)

补丁合并和树生命周期

我们鼓励频繁提交者负责自己的代码分支树,在那里他们聚合他们所负责的补丁和/或自己创建的补丁。 一旦分支已被审查和测试,可以提议将其包含在主分支中。

  • 分支(分段树)随时被合并到主干
  • 修正Bug可以直接并入主干
  • PRs(Poll Request)可以从任何来源发送到补丁邮件列表,如果树的质量好,并且提交的格式正确,将始终考虑包含进去
  • 分支(分段树 Staging trees)可以作为git基础设施项目的一部分,私有服务器,GitHub ...

几个关键词

  • PR Poll Request 合并请求
  • Staging tree 分段树,即一个代码分支。
  • Squashing commits 合并多个提交为一个提交