Zephyr贡献指南

说明

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中包含下面格式的信息就表示进行了签名

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

可以使用

git commit -s

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

git commit --amend -s

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

git push -f

贡献前提 链接到标题

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

代码仓库 链接到标题 

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匹配

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：

source zephyr-env.sh
./scripts/sanitycheck

uncrustify 链接到标题

自动format code style, Zephyr Coding Style

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***修改内容为：

#!/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到本地
git clone https://github.com/<your github id>/zephyr
git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git
  1. 创建分支
git checkout master
git checkout -b fix_comment_typo
  1. 修改,测试,修改,测试
  2. 添加要提交的文件
git add [file(s) that changed, add -p if you want to be more specific]
  1. 检查要提交的内容
git status
git diff --cached
  1. 提交代码到本地仓库
git commit -s
  1. push代码到远端
git push origin fix_comment_typo

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

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

git checkout master
git checkout -b fix_another_issue
  1. 如果reviewer需要你修改patch，可以在fork的repo中：
git fetch --all
git rebase --ignore-whitespace upstream/master
git rebase -i <offending-commit-id>^

进行修改修改完后

git add [file(s)]
git rebase --continue
git push --force origin fix_comment_typo
  1. 如果CI run fail，修改code在重新做rebase

Commit指南 链接到标题

每个git commit信息必须包含：

  • 少于72个字符的主题行，主题行后面是空白行。主题行标示修改的子系统前缀后面跟冒号和简短标题例如：
doc: update wiki references to new site
  • 描述修改内容，后面跟空行
  • 使用git commit -s自动添加Signed-off-by
  • 如果是fix issue，增加一行
Fixes #<issue number>.

Commit描述内容 链接到标题

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

其它要求 链接到标题

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

提交建议 链接到标题

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

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

贡献来源识别 链接到标题

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

Origin: Original

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

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

导入外部维护文件

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