1[上一页](README_CN.md)
2# 贡献代码
3
4我们非常欢迎和感谢各位开发者来活跃我们的社区。您可以通过提 GitHub issue的方式对您遇到的问题进行发问来寻求支持和讨论，也可以直接为您的代码改动创建拉取请求来合入到我们SDK的项目中。在创建issue或拉取请求之前，请参阅以下指南。
5
6#### 目录
7  * [行为守则](#行为守则)
8  * [许可协议](#许可协议)
9  * [工作流程](#工作流程)
10  * [提交指南](#提交指南)
11  * [贡献新的组件](#贡献新的组件)
12
13
14## 行为守则
15
16所有开发者都应遵守我们的[行为守则](CODE_OF_CONDUCT_CN.md)。请确保您在我们的社区中热情友好。
17
18## 许可协议
19
20此项目中的所有 SDK 驱动程序、组件、设备支持文件、开发板支持文件均使用 BSD-3-Clause 许可协议，许可协议副本请查看 [COPYING_BSD-3](COPYING-BSD-3)。对于使用 BSD-3-Clause 许可证的源文件，您可能会在头部看到类似的许可声明。
21```
22/*
23 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc.
24 * Copyright 2016-2020 NXP
25 * All rights reserved.
26 *
27 * SPDX-License-Identifier: BSD-3-Clause
28 */
29```
30还有一些源文件使用不同于BSD-3-Clause的许可证，例如ARM CMSIS Core相关的源代码使用 [Apache License 2.0](CMSIS/LICENSE.txt)许可协议。所有MCUXpresso SDK项目的许可信息可以在 [SW-Content-Register.txt](SW-Content-Register.txt) 中找到。
31
32## 工作流程
33本节描述了创建GitHub issue和代码拉取请求的流程。
34
35### 创建GitHub issue
36
37我们建议您通过创建GitHub issue的方式来向我们报告代码中的错误和Bug。如果您想要请求项目加入新的功能，请检查 [贡献新的组件](#贡献新的组件) 以提出您的想法。
38
39在提交issue之前，请做以下检查：
40* **将您的代码库定位到最新的main分支以查看问题是否仍然存在**，该问题可能已经在最新的main分支上修复。
41* **检查它是否在版本的Release Notes中被声明为已知问题**，如果您不在发行版本上，请检查main分支上最新发布版本的Release Notes。
42* **搜索现有的 GitHub issue，看看它是否已经被提出**，同样的问题可能已经被其他开发者提出。
43
44如果以上检查都没有帮助您解决问题，您可以通过[新问题](https://github.com/NXPmicro/mcux-sdk/issues/new/choose)来创建GitHub issue，请按照模板描述您的问题，解释问题并包含其他详细信息，以帮助我们高效地重现您的问题并提供支持。
45
46### 创建代码拉取请求
47
48如果您想将您的代码改动贡献到我们的项目，需要遵循GitHub创建拉取请求的流程。以下步骤需要 **Git** 知识。
49
50| :exclamation: 注意 |
51|:-----------------------------------------:|
52|如果您的代码贡献包含了一些新的源文件来实现某个组件，请确保首先按照流程[贡献新的组件](#贡献新的组件) 来跟我们进行沟通。|
53
541. 在我们的 GitHub 项目上点击 ‘Fork’，创建一个forked的工作仓库到您个人的 GitHub 账户。例如。 ```您的名字/mcux-sdk```
552. 将您的forked的代码仓库克隆到本地。 ```git clone https://github.com/yourname/mcux-sdk.git```
563. 在本地切换目录到克隆的代码仓库 ```mcux-sdk``` 文件夹。
57    ```
58    cd mcux-sdk
59    ```
604. 在工作仓库中添加新的远程（remote）```nxp```，来追踪我们恩智浦官方项目```NXPMicro/mcux-sdk```来获取最新的代码库。
61    ```
62    git remote add nxp https://github.com/NXPmicro/mcux-sdk.git
63    ```
645. 创建一个新的分支来准备代码修改和提交，该分支应该从您要合入的目标分支检出（checkout），例如nxp官方的远程仓库的main分支nxp/main。
65    ```
66    git fetch nxp
67    git checkout -b bugfix/fixing_yy nxp/main
68    ```
696. 进行代码修改，在本地分支中提交更改。编码风格和提交准备应遵循 [提交指南](#提交指南)：
70    ```
71    git add xxx
72    git commit -s
73    ```
747. 将本地分支推送到远程 github 存储库。
75    ```
76    git push origin HEAD:bugfix/fixing_yy
77    ```
788. 在浏览器中查看您在 GitHub 上forked的代码仓库，然后单击创建拉取请求按钮来查看您上一步推送的分支的提交信息，为分支创建拉取请求。请按照拉取请求的模板来描述您的拉取请求，以帮助代码评审者更好地理解您的修改逻辑。
79
80    如果代码评审者对您的拉取请求有一些评论，请及时更新拉取请求来提交根据相应评论进行的改动，**虽然不建议但可以** 修改您之前的提交并使用强制推送（```git push -f```）来方便地更新您的拉取请求。
81
82## 提交指南
83
84### 开发者原创认证 (DCO)
85受 [zephyr](https://docs.zephyrproject.org/latest/contribute/index.html) 的启发，我们希望采用 DCO 流程来鼓励开发者贡献代码并避免可能的法律风险。DCO 声明您的代码贡献属于您所有，并且您允许我们的项目在开源许可下使用您的代码贡献。完整的声明如下所示（该中文版本由开放原子开源基金会翻译）：
86
87```
88开发者原创声明
89第1.1版
90
91版权所有(C)2004,2006 Linux基金会及其贡献者。
92约克街660号，102套房，
93加利福尼亚州旧金山市94129
94
95任何人均可复制和分发本许可文件副本，但不得修改。
96
97开发者原创声明（第1.1版）
98
99在向本项目提交贡献之时，本人声明：
100
101(a) 该贡献全部或部分由本人创作，且本人有权根据当前文件中所示的开源许可证提交；或
102
103(b) 尽本人所知，该贡献所基于的在先作品已经过适当的开源许可证授权，且根据该开源许可证，本人有权在相同开源许可证（如当前文件中所示）下提交该修改后的作品（除非本人被允许根据不同的许可证提交），不论其是否全部或部分由本人创作；或
104
105(c) 该贡献是由作出(a)、(b) 或(c) 声明的其他人直接提供给本人，且本人未对其进行修改。
106
107(d) 本人理解并同意，本项目及贡献是公开的，且贡献（包括本人随附提交的全部个人信息，含本人签字）将被无限期存档，并可以与本项目或所涉开源许可证保持一致的情形下再被分发。
108
109```
110
111如果您同意该声明，只需在代码提交信息中添加签名，格式如下：
112```
113Signed-off-by：FIRST_NAME LAST_NAME <FIRST_NAME.LAST_NAME@nxp.com>
114```
115#### 使用 Git 命令行添加签名
116打开 Git bash，执行以下命令来添加签名。
117
118* 配置用户名和邮箱以用于提交信息的签名
119
120    如果您想为计算机上的所有Git代码仓库配置用户名和邮箱，您可以使用以下命令：
121    ```
122    git config --global user.name "FIRST_NAME LAST_NAME"
123    git config --global user.email "MY_NAME@example.com"
124    ```
125    否则，如果您只想在当前代码仓库中应用配置，请在当前代码仓库目录下使用：
126    ```
127    git config user.name "FIRST_NAME LAST_NAME"
128    git config user.email "MY_NAME@example.com"
129    ```
130* 添加签名到提交说明（commit message）
131
132    这很简单，只需使用 ```git commit -s ``` 提交您的代码修改，签名将自动添加到您的提交说明中。如果要向历史提交添加签名，例如最新一次提交，请使用 ```git commit --amend -s```。
133
134#### 使用GitHub Web 编辑器添加签名
135您也可以通过 GitHub Web 网页来准备您的代码更改并提交。由于目前 GitHub Web 网页还不支持提交代码时自动添加签名，您需要在提交说明的末尾手动添加签名信息。示例如下：
136![在 GitHub UI 中添加签名](docs/Contributing/add_signoff_for_github_editor.png)
137
138
139| :exclamation: 注意 |
140|:-----------------------------------------:|
141| SDK基础代码库使能了DCO检查来自动检查您的拉取请求是否包含签名信息。拉取请求中任意一笔提交中存在签名缺失的问题都会触发检查失败，此时需要您检查提交说明并对拉取请求进行相应的更新。**没有通过DCO检查的拉取请求不会被合入到项目中**。|
142
143### 编码风格
144
145**请遵循源代码中现有的编码约定。** 现有的源代码遵循以下一些常见规则：
1461. 为每个 if、else、do、while、for 和 switch 主体添加大括号，即使对于单行代码块也是如此。
1472. 缩进使用 4 个空格，而不是制表符(TAB)。
1483. 使用C89风格的单行注释，/* */。不允许使用 C99 样式的单行注释 //。
1494. 为代码添加注释。如果您要在现有驱动程序/组件中添加新功能/类型，请在头文件中添加适当的 doxygen 注释。
150
151### 提交准备
152
153在代码修改之后准备提交时，请参考以下指引来进行提交工作。
154
155请使用**英语**来组织提交说明，每条提交说明都应遵循以下要求：
156
157* 有一个简短而清晰的主题行。建议主题行长度限制为 72 个字符并使用祈使语气。如果要修复某个指定的GitHub issue，请从 ```Fixes #<issue number>``` 开始。
158* 主题行和描述正文之间用换行符分隔开。
159* 提交说明的正文部分，应描述：
160    * 做出了**什么**变化。
161    * 您**为什么**改变了这个方法，以及
162    * 您**如何**知道它有效。例如，您已在 x 板上验证运行测试。
163* 在您的提交说明中添加签名。
164
165每个提交都必须解决一个可识别的问题，并且必须在逻辑上是独立的。当一个拉取请求包含多笔提交时，请保证每一笔都不会破坏当前项目的编译和运行，这样可以在发生问题的时候通过二分法快速定位到具体是那一笔提交引入的问题。
166
167
168## 贡献新的组件
169如果您想贡献新的组件代码，这个组件包含一些新的源文件，请先发送电子邮件至 [项目维护者](susan.su@nxp.com) 交流您的想法。如果新组件使用除BSD-3-Clause以外的其他许可证，您需要在邮件描述中说明许可证信息，以便我们判断您的代码贡献是否会对当前项目造成污染。组件的许可证信息请遵循 [SW-Content-Register.txt](SW-Content-Register.txt) 中的条目来准备。
170