1[Previous Page](README.md) 2# Contribution Guidelines 3 4We greatly welcome and highly appreciate for your contribution. You could freely choose to either raise a GitHub issue or contributing your code change directly to our project. Please read through below guidelines before building your contribution. 5 6##### Table of Contents 7 * [Code of Conduct](#code-of-conduct) 8 * [Licensing](#licensing) 9 * [Developer Certification of Origin (DCO)](#developer-certification-of-origin-(DCO)) 10 * [Commit Guidelines](#commit-guidelines) 11 * [Contribution Workflow](#contribution-workflow) 12 * [Contributing New Components](#contributing-new-components) 13 14 15## Code of Conduct 16 17All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). Please make sure you are welcoming and friendly in our community. 18 19## Licensing 20 21All SDK drivers, components, device support files, board support files and driver examples in this project are under BSD-3-Clause license, license copy please check [COPYING_BSD-3](COPYING-BSD-3). For sources using BSD-3-Clause license, you may see similar copyright as below in the head of source file. 22``` 23/* 24 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc. 25 * Copyright 2016-2020 NXP 26 * All rights reserved. 27 * 28 * SPDX-License-Identifier: BSD-3-Clause 29 */ 30``` 31There are also components using different license, eg. the ARM CMSIS component is under [Apache License 2.0](CMSIS/LICENSE.txt). Overall license information for this project could be found in [SW-Content-Register.txt](SW-Content-Register.txt). 32 33## Developer Certification of Origin (DCO) 34Inspired by [zephyr](https://docs.zephyrproject.org/latest/contribute/index.html), we would like to adopt DCO process to encourage user contribution and avoid legally ambiguous situation. The DCO is a statement that you are the author of your contribution, and you allow our project to use your contribution under the open source license. The full statement is shown as below: 35``` 36Developer Certificate of Origin 37Version 1.1 38 39Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 40660 York Street, Suite 102, 41San Francisco, CA 94110 USA 42 43Everyone is permitted to copy and distribute verbatim copies of this 44license document, but changing it is not allowed. 45 46Developer's Certificate of Origin 1.1 47 48By making a contribution to this project, I certify that: 49 50(a) The contribution was created in whole or in part by me and I 51 have the right to submit it under the open source license 52 indicated in the file; or 53 54(b) The contribution is based upon previous work that, to the best 55 of my knowledge, is covered under an appropriate open source 56 license and I have the right under that license to submit that 57 work with modifications, whether created in whole or in part 58 by me, under the same open source license (unless I am 59 permitted to submit under a different license), as indicated 60 in the file; or 61 62(c) The contribution was provided directly to me by some other 63 person who certified (a), (b) or (c) and I have not modified 64 it. 65 66(d) I understand and agree that this project and the contribution 67 are public and that a record of the contribution (including all 68 personal information I submit with it, including my sign-off) is 69 maintained indefinitely and may be redistributed consistent with 70 this project or the open source license(s) involved. 71``` 72If you are agree with the statement, just simply add sign-off in your commit message, following format: 73``` 74Signed-off-by: FIRST_NAME LAST_NAME <FIRST_NAME.LAST_NAME@nxp.com> 75``` 76### Sign-off DCO if you are using Git command line 77Open Git bash to execute below commands for adding sign-off. 78 79* Config user name and email for sign-off message 80 81 If you are willing to configure user name and email address for every repository on you computer, use below commands: 82 ``` 83 git config --global user.name "FIRST_NAME LAST_NAME" 84 git config --global user.email "MY_NAME@example.com" 85 ``` 86 else if you only want to set the configuration in current single repository, use: 87 ``` 88 git config user.name "FIRST_NAME LAST_NAME" 89 git config user.email "MY_NAME@example.com" 90 ``` 91* Add sign-off to commit message 92 93 This is quite simple, just use ```git commit -s ``` to commit your message, sign-off will be automatically added to your commit message. If you want to add sign-off to an existing commit, for example, the latest commit, use ```git commit --amend -s```. 94 95### Sign-off DCO if you are using GitHub Web Editor 96It's currently not supported automatically adding sign-off when you Commit change directly using GitHub Web UI. You need to manually add sign-off message in the end of your commit message. Example as below: 97 98 99 100| :exclamation: NOTE | 101|:-----------------------------------------:| 102| DCO check will be done automatically to your pull requests. If there's sign-off mismatch issue in any commit or no sign-off is detected, the check will fails, you could check details and update your PR accordingly.| 103 104## Commit Guidelines 105 106### Coding Style 107 108**Please follow the existing coding conventions in sources.** Some common rules should be followed as below: 1091. Add braces to every if, else, do, while, for and switch body, even for single-line code blocks. 1102. Use 4 spaces, instead of tabs for indent. 1113. Use C89-style single line comments, /* */. The C99-style single line comment, //, is not allowed. 1124. Code should be well documented, add proper doxygen comments if you are adding new function/types in existing drivers/components. 113 114### Commit Preparation 115 116There are some requirements for making commits, please carefully review the following guidelines before submitting your change. 117 118Each commit message should follow below requirements: 119 120* Have a short and clear subject line. A suggest subject line length limits to 72 characters and uses imperative mood. If it's to fix reported issue, start with ```Fixes #<issue number>```. 121* Add a newline to separate subject line and description body. 122* The description body should describe: 123 * **What** the change does. 124 * **Why** you change the approach, and 125 * **How** you know it works - for example, you have verified run test on x board. 126* Add sign-off in your commit. 127 128Commits must build cleanly when applied on top of each other, thus avoiding breaking bisectability. Each commit must address a single identifiable issue and must be logically self-contained. 129 130## Contribution Workflow 131This section describes the flow for raising an issue or contributing through pull-request. 132 133### Raise an issue 134 135We suggest you raise an issue to report bugs only, if you are requesting new feature, please check the [Contributing New Components](#contributing-new-components) to suggest your idea. 136 137Before submitting issue, please do below checks: 138* **Rebase your code base to latest main branch to see if the issue still exists**, the issue could have already been fixed in the latest code base. 139* **Check if it is stated as known-issue in release notes**, if you are not on release tag, check release notes for latest release tag on main branch. 140* **Search existing GitHub issues to see if it has already been reported**, the same issue could be raised by other developers already. 141 142If above checks does not help the issue, you may report issue via [New issue](https://github.com/NXPmicro/mcux-sdk/issues/new/choose), please follow the template to describe your issue, explain the problem and include additional details to help us reproduce and move on efficiently. 143 144### Create a pull-request 145 146If you want to contribute your code back to our project, need to follow the pull-request flow. Knowledge for **Git** is required with below steps. 147 148| :exclamation: NOTE | 149|:-----------------------------------------:| 150| If you want to contribute new features, please make sure the new features are communicated follow the flow [Contributing New Components](#contributing-new-components) firstly.| 151 1521. Click ‘Fork’ on our GitHub project, create a forked repo to your personal GitHub account. eg. ```yourname/mcux-sdk``` 1532. Clone your forked repo to local repository. ```git clone https://github.com/yourname/mcux-sdk.git``` 1543. Change into the ```mcux-sdk``` folder which hosts local repository. 155 ``` 156 cd mcux-sdk 157 ``` 1584. Add new remote ```nxp``` in the repository to be able to get latest code base in ```NXPMicro/mcux-sdk```. 159 ``` 160 git remote add nxp https://github.com/NXPmicro/mcux-sdk.git 161 ``` 1625. Checkout a new branch for your contribution, the branch should be check out from the origin branch you want to contribute back to. eg. nxp/main branch 163 ``` 164 git fetch nxp 165 git checkout -b bugfix/fixing_yy nxp/main 166 ``` 1676. Do code your change, commit the change in local branch. The coding style and commit preparation should follow [Commit Guidelines](#commit-guidelines): 168 ``` 169 git add xxx 170 git commit -s 171 ``` 1727. Push your local branch to your remote github repo. 173 ``` 174 git push origin HEAD:bugfix/fixing_yy 175 ``` 1768. Go to your forked repo on GitHub and click on the Compare & pull request button for the branch you just pushed to open a pull request. Please also follow the template description to describe your pull request to help reviewers to understand your logic. 177 178 For the final step to update pull-request to incorporate all suggested changes in review comments, **although it's not suggested but it's OK** to amend your previous commit and use force push to update your PR conveniently. 179 180 181## Contributing New Components 182If you want to contribute new components, please send an email to [project maintainer](susan.su@nxp.com) to communicate your idea first. If the new component has a different license other than BSD-3-Clause, you need to prepare a description for the license information in the email description for us to decide whether the contribution will pollute the project. Description for the new license need to follow the component entry in [SW-Content-Register.txt](SW-Content-Register.txt). 183 184
