自由可扩展.
欢迎来到智能路由器开发指南OpenWrt网站OpenWrt 是一个开源的嵌入式Linux操作系统发行版，OpenWrt广泛应用于家庭路由器，智能手表等设备上，其带有上千款软件，可以方便你来扩展功能。 OpenWrt本身的代码以GNU GPL许可协议发行，其带有的第三方软件遵守自己的开源协议。大多也为GNU GPL。 其管理页面采用Apache许可协议发行。 如何贡献代码OpenWrt目前仍在持续更新中。我们希望更多的人参与其中并贡献自己的成果。如果你做出了有用的修改，尽量把它集成到项目中，这能够使OpenWrt更加完善，同时你的修改也会集成到未来的版本中。 无论个人或者团队希望向OpenWrt提交代码，若不熟悉提交代码的流程，可能会遇到困扰。本文搜集了很多帮助你成功提交代码的建议。 这个文档尽量列出对所有人都高效的提交补丁流程。 重复做如下步骤很重要在哪儿讨论：文档在你实施之前最好先形成文档。写文档的过程常常可以发现哪些地方能够进一步改进，同时也要及时更新文档。 创建和提交补丁1.创建补丁所有OpenWrt的变更都是以补丁的形式实现的。补丁是应该基于主干根目录而不是底层子目录。 确保你的补丁不包含任何多余文件。补丁生成后一定要再次进行检查，以确保准确性。 如果你的补丁包括的修改内容很多，可以按照逻辑分割成几个补丁进行提交，这样有助于OpenWrt其他开发人员进行评审。如果希望补丁能够顺利提交，这点尤其重要。 创建补丁的工具如下，按性能顺序列出： 2.描述补丁尽量明确的描述修改包含的技术细节。最差的描述例子：“对包X的bug修改”、“修正了包X的问题”、“平台X的升级补丁，请应用”。 最好的效果是补丁描述不用修改，直接作为OpenWrt源码管理系统中相应提交的注释信息。请参考下面的第13点说明。 如果描述过长，需要将补丁分割成多个。请参考接下来的第3点说明。 当提交补丁或补丁集合时，请包含完整的描述和验证信息，不要仅说明这是第几个版本的补丁（集合）。因为有些集成人员也不了解旧版本的补丁，所以不要期待他们会去找旧版本的补丁或描述并放到新的补丁里去。补丁的描述应该由提补丁的人自己填写完整，这对集成人员和评审人员都有益。 如果补丁修正了一个已经登记过的bug，请标注bug编号。 3.分割补丁如果一个补丁修改了多个逻辑功能，请分割成只修改单个逻辑功能的补丁文件。如，补丁既包含了bug修正，又包含一个模块的功能完善，那么可以分成两个或多个补丁。另外，对多个文件修改同一个问题，可以集中到一个补丁文件包中，这样一个补丁正好包含一个逻辑功能的修改。 如果一个补丁依赖于另一个补丁，要在补丁描述中注明“此补丁依赖于补丁XX”。如不能对大的补丁分割为更小的补丁，那就只能等待15天甚至更长的时间来进行代码评审和集成。 4.代码格式检查检查你的补丁的格式是否正确。如果没有检查，会浪费评审员的时间，补丁也会被直接拒绝。 5.选择e-mail收件人如果Makefile中含有维护者的名字，那么就给维护者发邮件。除非有特殊原因，否则都要抄送OpenWrt开发者邮件列表openwrt-devel@lists.openwrt.org。如果没有列出维护者，请发送补丁到[https://lists.openwrt.org/cgi-bin/mailman/listinfo/openwrt-devel primary OpenWrt 开发者的邮件列表]。许多OpenWrt开发者都在这份列表里，他们可以对补丁提出意见或建议。 6.不要包含MIME，链接，不要压缩，不要带附件，纯文本就好OpenWrt开发者会阅读你的补丁内容并提出建议。OpenWrt开发者通常使用标准的邮件客户端，这些客户端工具必须能够引用补丁内容，以便开发者针对代码相应部分做注释。因此，所有的补丁内容应该在邮件中体现出来。警告：小心文件编辑器的自动换行，可能破坏你的补丁，例如剪切然后粘贴的操作。 不管压缩与否，不要以MIME附件的形式发送补丁。许多流行的e-mail客户端不支持纯文件的MIME附件，补丁就无法追加注释。 特殊情况除外：如果你的邮件客户端破坏了补丁，其他人也许会要求你使用MIME重新发送。 7.邮件大小不建议使用大补丁。如果未压缩的补丁超过了300KB，推荐先把补丁保存在网络服务器上，然后发送补丁文件的URL链接。 8.不要气馁，再次提交在提交补丁后，请耐心等待。如果开发者接受了该补丁，在源代码管理系统中可以看到补丁被集成到了新版本中。如果该代码没有出现在源代码管理系统中，可能有很多种原因，只能自己查找原因，修改错误的地方，重新提交更新后的补丁。 还有一种常见的情况，开发者有或者没有说明就丢弃了你的补丁。这是非常自然的情况。如果你的补丁被移除，可能的原因有如下几种情况。 如有疑问，请向openwrt-devel邮件列表发邮件寻求帮助。 9.在邮件标题中包含补丁名称由于开发者邮件列表中的邮件太多，大家约定在邮件主题前面加上前缀[PATCH]，这样很容易识别哪些是补丁邮件。 10.加上签名为了更好的记录谁做了什么，使用“sign-off”标签在补丁中做标记。“sign-off”在补丁尾部，独占一行，证明你是补丁作者或有权利将补丁提交为开源补丁。“sign-off”使用规则很简单，例如：
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
然后只要加一行： Signed-off-by: Random J Developer <random@developer.example.org> 要使用真实姓名（非别名或匿名）。有人还在补丁尾部添加其它额外的标签，可以仅忽略其它标签，或者可以用于公司内部标记， 或指出sign-off有什么特别的地方。如果你是维护者角色，有时因为维护的代码树和补丁提交者的代码树可能有小的不一致， 所以需要对补丁稍作修改，以便于集成。如果严格执行规则(c)，应该要求提交者重做补丁，但这样浪费时间和精力。 规则(b)允许调整补丁代码，但是因此而修改别人的代码，不是很礼貌。为了解决类似问题，推荐这样做： 在尾部的Signed-off-by之后加上修改说明，再加上你的Signed-off-by。这些都非强制性的，就像邮件/姓名前的描述信息。 用方括号括起来，这样够醒目，能够显示出是你做的最后修改。例如： Signed-off-by: Random J Developer <random@developer.example.org> [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> 如果维护的是一个稳定版分支，希望实时了解谁贡献了代码，跟踪修改，集成补丁，避免补丁提交者被误解，这个方法特别有效。 注意，在任何情况下，不要修改提交者的名字，这部分内容会在修改列表(changelog)中显示。 关于向后移植（新版本的功能移植到旧版本）的特别提醒：有一个很常见、很有用的方法， 在提交的说明信息顶部加一条关于原补丁的信息（在标题之后），便于追踪代码的修改过程。例如： Date: Wed Jul 25 15:14:50 2012 +0300 [generic] add missing symbols [backport r12345] 不管什么格式，如果有人检查代码的修订历史，或解决代码中的bug，该信息会提供很有效的帮助。 11.何时使用Acked-by:和Cc:没有直接参与制作或发布补丁，但是希望记录他们对该补丁的评审工作的维护者，常常使用“Acked-by:”标签。“Acked-by:”没有”Signed-off-by:”正式。它记录补丁由谁评审通过。因此负责集成补丁的维护者有时会使用“Acked-by:”记录谁是该补丁的评审者。 “Acked-by:”不需要对整个补丁评审通过。如，一个补丁关系到多个组件，其中一个包的维护者添加了“Acked-by:”标签，代表该组件维护者认为该补丁不影响其维护的组件。 如果某人可能对这个补丁发表意见，或对补丁内容感兴趣，可以加上“Cc:”标签。只有这个标签里的人，可以不做关于补丁的工作，只是记录谁有可能感兴趣并参加相关讨论。 12.使用标签Reported-by:, Tested-by: 和Reviewed-by:如果该补丁修正了某个问题，这个问题是由某人报告的，可以使用“Reported-by:”记录报告者信息。请注意该标签必须经过报告者同意才能添加，尤其是在非公共论坛报告问题的情况。如果认真记录了问题报告者的工作，有利于报告者持续提供帮助。 “Tested-by:”标签说明该补丁内容已经由该标签所标注的人测试通过。它说明有些测试内容已经完成，为测试人员测试该补丁提供了一定帮助。 “Reviewed-by: ”记录了谁评审通过该补丁，包括评审者的评价和意见，例如： Reviewer's statement of oversight By offering my Reviewed-by: tag, I state that: (a) I have carried out a technical review of this patch to evaluate its appropriateness and readiness for inclusion into OpenWrt. (b) Any problems, concerns, or questions relating to the patch have been communicated back to the submitter. I am satisfied with the submitter's response to my comments. (c) While there may be things that could be improved with this submission, I believe that it is, at this time, (1) a worthwhile modification to OpenWrt, and (2) free of known issues which would argue against its inclusion. (d) While I have reviewed the patch and believe it to be sound, I do not (unless explicitly stated elsewhere) make any warranties or guarantees that it will achieve its stated purpose or function properly in any given situation. “Reviewed-by”标签代表补丁对OpenWrt做出的修改，没有造成技术问题。所有感兴趣并评审了补丁的人 （做了评审工作的人）都可以加上“Reviewed-by”。这个标签记录了评审代码的贡献，也记录了补丁评审工作的程度。 “Reviewed-by”标签是由相关领域的专业人士评审补丁后添加，一般情况下，这种补丁更有希望被集成到OpenWrt。 13.补丁格式规范补丁标题规范： Subject: [PATCH 001/123] [section] summary phrase 补丁说明信息的规范： 按格式规范写标题，大多数邮件客户端支持按字母排序，非常方便，注意序列号不足位数的情况填充0，这样就不影响字母排序。 标题中的“section”说明补丁修改了OpenWrt哪个部分，例如：
标题中的“summary phrase”应简洁的描述邮件所含补丁。注意不要使用文件名，补丁集中不同补丁不要使用相同的"summary phrase"（补丁集是多个相关的补丁） 谨记“summary phrase”将成为补丁的唯一标识，在源码管理系统中，经常用到这个标识。如开发者讨论时、大家在google搜索时、一段时间后大家在源码管理系统中快速浏览数千个补丁时，往往只看这个标识。 因此，“summary phrase”不能超过70~75个字符，描述补丁修改了的内容和修改的必要性。做到简单明了的描述补丁很难，但是“summary phrase”一定要做到。 “summary phrase”如果有前缀，用方括号[]括起来，如: "<summary phrase>"。前缀不包含在“summary phrase”中，它描述了补丁处理方式。例如，补丁有多个版本时，为了方便进行代码评审，前缀可以是补丁的版本(例如, "v1, v2, v3")，或者是"RFC"表示需要大家的评审意见。如果一个补丁集有4个补丁，前缀可以是1/4、2/4、3/4、4/4，开发者就了解了补丁的顺序，保证以正确的顺序应用补丁、评审补丁。一些示例如下： Subject: [PATCH] [packages] e2fsprogs: Bump to 1.41.3 Subject: [PATCH] [x86] generic: switch to 3.3 Subject: [PATCHv2 001/207] [ar71xx] enable sysupgrade on the WRT160Nl “from”是信息主体的第一行，格式如下： From: Original Author <author@example.com> “from”独占一行，永久性记录补丁作者的贡献。如果没有这一行，邮件头中的发起人将被作为补丁作者进行记录。 补丁的信息描述将永久性记录在源码的修改日志中。对读者而言，即使已经忘记了关于补丁的讨论细节，也应较容易读懂描述信息，所以描述信息应该具有相当的参考价值。包括补丁解决的问题有何种现象（如内核日志，oops信息等），大家查看修改日志时将非常有用。如果补丁修正了编译错误，不需要把整个错误信息包含进来，只要搜索修改日志时方便找到就足够了。就像“summary phrase”，描述简单明了。 符号标记“---”独占一行，处理补丁的工具以此标记识别出修改日志结束。 使用“---”标记之后的额外注释信息，一种情况是diffstat（补丁变更代码的统计信息），包括修改了哪些文件，每个文件增加/删除了多少行。diffstat对于较大的补丁很有用。一些临时的信息、或维护者需要的信息、不需要永久的记录在修改日志中，可以放在“---”之后，作为额外注释信息。例如“patch changelogs”描述了补丁v1到v2版本之间修改了哪些内容。 更多关于补丁格式规范的细节，见参考资料： 跟踪补丁的进展情况补丁发布到开发者邮件列表后，可以使用''Patchwork''来跟踪进展情况：https://patchwork.ozlabs.org/project/openwrt/list/ 参考资料翻译： 张永智，程晶于2015年12月翻译 ，本书已上市，原计划该内容放在书的附录中，但种种原因未放在书中。 |
图书当前状态-已于2016年9月出版
相关项目友情链接参考资料 |