Zephyr贡献指南

Creative Commons
本作品采用知识共享署名
发表于 | 分类于 | | 阅读次数：

说明

License

Zephyr使用Apache 2.0 License.Zephyr也导入了其它项目的代码，这些项目代码使用其它License。
如果你要导入到Zephyr的代码使用了非Apache 2.0 License，需要由Zephyr理事会批准。

DCO

Developer Certification of Origin
为了确保符合License许可,Zephyr项目要求遵循DCO。
DCO是每个开发者做出贡献的证明，在提交信息中开发者加入一个DCO签名，表示同意DCO。

DCO签名方法

在commit中包含下面格式的信息就表示进行了签名

1
Signed-off-by: FrankLi <lgl88911@163.com>

可以使用

1
git commit -s

如果commit时忘了sign off，可以使用

1
git commit --amend -s

如果已经push到github，加了签名后可以强制推送

1
git push -f

贡献前提

作为贡献者，应该熟悉如何配置，安装，使用Zepyhyr.
应该熟悉常见的开发工具：例如git,cmake和github平台。

代码仓库

1
git clone https://github.com/zephyrproject-rtos/zephyr

Pull Request & Issue

在提交patch前做下面几件事确认：

  1. Zephyr github issue & open pull request内没有提及
  2. mail list和freenode IRC Channel内没有提及
  3. 在Zephyr-devel mailing list内提交和讨论patch做法

持续集成CI

Zephyr项目运行一个CI系统，当有Pull Requst(PR)发生时,CI验证以下几个方面：

  • Git commit格式
  • Coding Style
  • 各种 architectures 和 boards的编译检查(BUILD ERROR)
  • 编译和检验文档的变化

CI运行在云端，除了提交PR会触发CI，向PR添加评论也会触发CI。
CI运行的状态可以在PR页面的底部找到，会提示如下状态：
“All checks have passed”
“All checks have failed”
如果没有通过可以点击”Details”链接跳到详细信息，查看失败的原因。点击“Tests”选项卡查看失败时控制台的输出消息

工具和Git设置

Signed-off-by

name和email需要和Singed off匹配

1
2
git config --global user.name "FrankLi"
git config --global user.email "lgl88911@163.com"

gitlint

本地执行gitlint将运行和CI一样的动作。
gitlint只会检查HEAD，因此每次commit后都需要运行gitlint，或者用–commit来指定要检查的版本范围

sanitycheck

sanitycheck用来检验提交的代码是否破坏了tests & samples结果。在QEMU上运行各种kernel测试，一些Sample无法在QEMU上执行，因此仅仅执行编译测试。
在提出pull request前需要在本地执行sanitycheck：

1
2
source zephyr-env.sh
./scripts/sanitycheck

uncrustify

自动format code style, Zephyr Coding Style

1
2
sudo apt install uncrustify
uncrustify --replace --no-backup -l C -c $ZEPHYR_BASE/scripts/uncrustify.cfg my_source_file.c

Coding Style

参考 Linux kernel coding style, Linux kernel GPL-licensed 工具 checkpatch 可以用来检查Coding style,在进行commit时自动调用checkpath来检查，创建文件$ZEPHYR_BASE/.git/hooks/pre-commit修改内容为：

1
2
3
#!/bin/sh
set -e exec
exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl -

贡献Workflow

少量多次提交，提交时劲量多做变更说明，更新对应的文档。提交前做彻底的测试。
Zephyr Git典型workflow：

  1. 在Github的个人账号内fork Zephyr

  2. clone fork到本地

    1
    2
    git clone https://github.com/<your github id>/zephyr
    git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git

  3. 创建分支

    1
    2
    git checkout master
    git checkout -b fix_comment_typo

  4. 修改,测试,修改,测试

  5. 添加要提交的文件

    1
    git add [file(s) that changed, add -p if you want to be more specific]

  6. 检查要提交的内容

    1
    2
    git status
    git diff --cached

  7. 提交代码到本地仓库

    1
    git commit -s

  8. push代码到远端

    1
    git push origin fix_comment_typo

  9. 在web fork的仓库内进行pull request，并添加reviewer(根据repo下的CODEOWNERS文件)

  10. 等待pull request review期间，可以在其它分支上继续工作

    1
    2
    git checkout master
    git checkout -b fix_another_issue

  11. 如果reviewer需要你修改patch，可以在fork的repo中：

    1
    2
    3
    git fetch --all
    git rebase --ignore-whitespace upstream/master
    git rebase -i <offending-commit-id>^

    进行修改修改完后

    1
    2
    3
    git add [file(s)]
    git rebase --continue
    git push --force origin fix_comment_typo

  12. 如果CI run fail，修改code在重新做rebase

Commit指南

每个git commit信息必须包含：

  • 少于72个字符的主题行，主题行后面是空白行。主题行标示修改的子系统前缀后面跟冒号和简短标题例如：

    1
    doc: update wiki references to new site

  • 描述修改内容，后面跟空行

  • 使用git commit -s自动添加Signed-off-by
  • 如果是fix issue，增加一行
    1
    Fixes #<issue number>.

Commit描述内容

描述内容需要说明做了那些修改和未什么修改，不允许有空内容。必须包含下面内容：
修改了什么
为什么怎么修改
做了什么架设
你如何知道这样修改能工作：例如做了什么测试

其它要求

Commit信息必须简洁
Commit必须通过CI检查
每次Commit都必须解决一个单独的问题，Commit之间是独立的
有大的新功能添加时，必须在测试框架中添加新功能的自动测试。所有新功能的API必须要有文档和测试，测试覆盖率要超过80%

提交建议

如果有新功能的需求或者建议可以通过github以issue的方式提交。
如果有打算实现一个新功能首先提交一个RFC(requests for comments)issue,供Zephyr项目组评估。
建议issue应包括以下信息：

  • 建议概述
  • 动机和用处
  • 设计细节
  • 备选方案
  • 测试策略
    如果只是小特性可以直接Pull request

贡献来源识别

当添加新文件时需要详细说明文件来源，详细说明预期用途，如果提交文件是Zephyr的原始文件，commit消息应包含下面内容：

1
Origin: Original

如果是从外部项目导入文件，commit消息应包含：原始项目的详细关于信息，项目地址，原始文件的SHA-ID，预期目的，以及该文件是否将由Zephyr维护，例如：
导入本地维护文件

1
2
3
4
5
6
Origin: Contiki OS
License: BSD 3-Clause
URL: http://www.contiki-os.org/
commit: 853207acfdc6549b10eb3e44504b1a75ae1ad63a
Purpose: Introduction of networking stack.
Maintained-by: Zephyr

导入外部维护文件

1
2
3
4
5
6
Origin: Tiny Crypt
License: BSD 3-Clause
URL: https://github.com/01org/tinycrypt
commit: 08ded7f21529c39e5133688ffb93a9d0c94e5c6e
Purpose: Introduction of TinyCrypt
Maintained-by: External

原文参考

http://docs.zephyrproject.org/contribute/contribute_guidelines.html