CONTRIBUTING.md

   1 [Previous Page](README.md)
   2 # Contribution Guidelines
   3
   4 We 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
  17 All 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
  21 All files 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 copyrights to the one below in the header of a 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 ```
  31 There are also components using different licenses, such as the zlib component which is under the zlib license. Overall, license information for this project can be found in README.md
  32
  33 ## Developer Certification of Origin (DCO)
  34 We are adopting the DCO process to encourage user contribution and avoid legally ambiguous situations. 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 ```
  36 Developer Certificate of Origin
  37 Version 1.1
  38
  39 Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
  40 660 York Street, Suite 102,
  41 San Francisco, CA 94110 USA
  42
  43 Everyone is permitted to copy and distribute verbatim copies of this
  44 license document, but changing it is not allowed.
  45
  46 Developer's Certificate of Origin 1.1
  47
  48 By 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 ```
  72 If you are agree with the statement, just simply add sign-off in your commit message, following format:
  73 ```
  74 Signed-off-by: FIRST_NAME LAST_NAME <FIRST_NAME.LAST_NAME@nxp.com>
  75 ```
  76 ### Sign-off DCO if you are using Git command line
  77 Open 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
  96 It'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.
  97
  98 | :exclamation: NOTE |
  99 |:-----------------------------------------:|
 100 | 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.|
 101
 102 ## Commit Guidelines
 103
 104 ### Coding Style
 105
 106 **Please follow the existing coding conventions in sources.** Some common rules should be followed as below:
 107 1. Add braces to every if, else, do, while, for and switch body, even for single-line code blocks.
 108 2. Use tabs for indent.
 109
 110 ### Commit Preparation
 111
 112 There are some requirements for making commits, please carefully review the following guidelines before submitting your change.
 113
 114 Each commit message should follow below requirements:
 115
 116 * Have a short and clear subject line. A suggest subject line length limits to 75 characters and uses imperative mood. If it's to fix reported issue, start with ```Fixes #<issue number>```.
 117 * Add a newline to separate subject line and description body.
 118 * The description body should describe:
 119     * **What** the change does.
 120     * **Why** you change the approach, and
 121     * **How** you know it works - for example, you have verified run test on x board.
 122 * Add sign-off in your commit.
 123
 124 Commits 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.
 125
 126 ## Contribution Workflow
 127 This section describes the flow for raising an issue or contributing through pull-request.
 128
 129 ### Raise an issue
 130
 131 We 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.
 132
 133 Before submitting issue, please do below checks:
 134 * **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.
 135 * **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.
 136 * **Search existing GitHub issues to see if it has already been reported**, the same issue could be raised by other developers already.
 137
 138 If above checks does not help the issue, you may report issue via [New issue](https://github.com/nxp-imx/mfgtools/issues), please follow the template to describe your issue, explain the problem and include additional details to help us reproduce and move on efficiently.
 139
 140 ### Create a pull-request
 141
 142 If 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.
 143
 144 | :exclamation: NOTE |
 145 |:-----------------------------------------:|
 146 | 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.|
 147
 148 1. Click ‘Fork’ on our GitHub project, create a forked repo to your personal GitHub account. eg. ```yourname/mfgtools```
 149 2. Clone your forked repo to local repository. ```git clone https://github.com/yourname/mfgtools.git```
 150 3. Change into the ```mfgtools``` folder which hosts local repository.
 151     ```
 152     cd mfgtools
 153     ```
 154 4. Add new remote ```nxp``` in the repository to be able to get latest code base in ```NXPMicro/mfgtools```.
 155     ```
 156     git remote add nxp https://github.com/yourname/mfgtools.git
 157     ```
 158 5. 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
 159     ```
 160     git fetch nxp
 161     git checkout -b bugfix/fixing_yy nxp/main
 162     ```
 163 6. Do code your change, commit the change in local branch. The coding style and commit preparation should follow [Commit Guidelines](#commit-guidelines):
 164     ```
 165     git add xxx
 166     git commit -s
 167     ```
 168 7. Push your local branch to your remote github repo.
 169     ```
 170     git push origin HEAD:bugfix/fixing_yy
 171     ```
 172 8. 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.
 173
 174     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.
 175
 176
 177 ## Contributing New Components
 178 If you want to contribute new components, please send an email to [project maintainer](Frank.Li@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.