|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We appreciate your contributions! Because this is an open source project, we want to keep it as easy as possible to contribute changes. However, we need contributors to follow a few guidelines. |
| 4 | + |
| 5 | +## Contributor agreement |
| 6 | + |
| 7 | +For us to accept your pull request, we need you to agree to our [contributor agreement](http://developer.mbed.org/contributor_agreement/) to give us the necessary rights to use and distribute your contributions. (To click through the agreement, create an account on mbed.com, and log in.) |
| 8 | + |
| 9 | +## Enhancements and bugs |
| 10 | + |
| 11 | +Enhancements are: |
| 12 | + |
| 13 | +* New features implementation. |
| 14 | +* Code refactoring. |
| 15 | +* Coding rules or coding style improvements. |
| 16 | +* Code comments improvement. |
| 17 | +* Documentation work. |
| 18 | + |
| 19 | +Bugs are: |
| 20 | + |
| 21 | +* Issues that application users and the ARM mbed team raise. |
| 22 | +* Issues the ARM mbed team creates internally from the Continuous Integration pipeline and build servers. |
| 23 | +* Issues that developers and the ARM mbed team detect using automation tools, such as compilers, sanitizers, static code and analysis tools. |
| 24 | + |
| 25 | +## Workflow |
| 26 | + |
| 27 | +### Forking and cloning this repository |
| 28 | + |
| 29 | +First [fork](https://help.github.com/articles/fork-a-repo/) this repository in GitHub. Then, clone it locally with: |
| 30 | + |
| 31 | +``` |
| 32 | +$ git clone <repo-link> |
| 33 | +``` |
| 34 | + |
| 35 | +Now, you can create separate branches in the forked repository and prepare pull requests with changes. |
| 36 | + |
| 37 | +### Issues solving |
| 38 | + |
| 39 | +To solve issues, follow the steps below: |
| 40 | + |
| 41 | +1. A user (any user) files an issue. |
| 42 | +1. A gate-keeper assigns a proper label to the issue. |
| 43 | +1. A user who wants to fix the issue, the bug fixer, forks and clones the repository. |
| 44 | +1. Optional: the bug fixer asks for and receives clarifications using the Issues tab's Comment section. |
| 45 | +1. The bug fixer creates a pull request that fixes the issue. |
| 46 | +1. Others review the pull request. |
| 47 | +1. The bug fixer handles all code review comments. |
| 48 | +1. A gate-keeper accepts the pull request. |
| 49 | +1. The pull request merges successfully. |
| 50 | + |
| 51 | +### Code review |
| 52 | + |
| 53 | +The code review process catches both style and domain-specific issues. It also follows and respects the _definition of done_. Please make sure your code follows the style of the source code you are modifying. A gate-keeper must review each pull request before we can merge the pull request to the master branch. |
| 54 | + |
| 55 | +## Issues and bug reporting |
| 56 | + |
| 57 | +Please report all bugs using the Issues tab on the GitHub page. This process helps us collaborate on issues promptly. One of our gate-keepers (developers responsible for quality and the repository) will review the issue and assign a label, such as _bug_, _enhancement_, _help wanted_ or _wontfix_. |
| 58 | + |
| 59 | +## How to contribute |
| 60 | + |
| 61 | +You can file a bug, help fix a bug or propose a new feature (or enhancement) and implement it yourself. If you want to contribute, please see below: |
| 62 | + |
| 63 | +* Bug reports: File a bug report in the Issues tab of this repo to let us know there are problems with the code. |
| 64 | + * Make sure your bug report contains a simple description of the problem. |
| 65 | + * Include information about the host computer's configuration and OS or VM used. |
| 66 | + * Include information about the application's version. All applications should have at least a `--version` switch you can use to check the version. |
| 67 | + * Copy and paste useful console dumps and configuration files' content. Please use [fenced code blocks](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) to encapsulate code snippets. |
| 68 | +* New features or bug fix: Create a pull request with your changes. |
| 69 | +* General feedback: Give feedback by posting comments on existing pull requests and issues. |
| 70 | + |
| 71 | +### Simple workflow for bug fixes |
| 72 | + |
| 73 | +* Select an issue to fix from open issues. |
| 74 | +* Fork the repository you wish to modify. |
| 75 | +* Locally clone your fork, and create a separate branch to fix the issue. |
| 76 | + |
| 77 | +Note: In this example we will fix issue #38. |
| 78 | + |
| 79 | +``` |
| 80 | +$ git clone <fork-repo-link> |
| 81 | +$ git checkout -b issue_38 |
| 82 | +... add changes locally to fix an issue |
| 83 | +``` |
| 84 | + |
| 85 | +* Add and commit your changes. |
| 86 | + |
| 87 | +``` |
| 88 | +$ git add . |
| 89 | +$ git commit -m "Add fix for issue #38" -m "More verbose explanation of the change/fix" |
| 90 | +$ git push origin issue_38 |
| 91 | +
|
| 92 | +``` |
| 93 | + |
| 94 | +* Push changes to GitHub. |
| 95 | +* Create pull request from GitHub (your fork's dashboard). |
| 96 | + |
| 97 | +### Branch naming conventions |
| 98 | + |
| 99 | +We prefer you use a standard naming convention when creating pull requests. Here are a few examples of branch name prefixes you could use when creating a pull request from your fork: |
| 100 | + |
| 101 | +* `issue_` - branch with fix for issue. For example, `issue_38`. |
| 102 | +* `doc_` - documentation update. For example, `doc_add_faq`. |
| 103 | +* `devel_` - development of a new feature. For example, `devel_udp_client_test`. |
| 104 | +* `test_` - when pull request will consist of only new/updates to test cases. For example, `test_paralllel_execution`. |
| 105 | + |
| 106 | +## Coding style and coding rules |
| 107 | + |
| 108 | +This chapter attempts to explain the basic styles and patterns in mbed test tools projects. Do the following to produce new code and update existing code. |
| 109 | + |
| 110 | +### Code like a Pythonista: idiomatic Python |
| 111 | + |
| 112 | +Please do your best to follow the [Idiomatic Python](http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html) interactive tutorial. |
| 113 | + |
| 114 | +### Style guide for Python code |
| 115 | + |
| 116 | +Please see [PEP 0008 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/) for details. |
| 117 | + |
| 118 | +### Whitespace |
| 119 | + |
| 120 | +* 4 spaces per indentation level. |
| 121 | +* No hard tabs. |
| 122 | +* Never mix tabs and spaces. |
| 123 | +* One blank line between functions. |
| 124 | +* Two blank lines between classes. |
| 125 | +* No whitespace at the end of a line. |
| 126 | + |
| 127 | +* Add a space after "," in dicts, lists, tuples and argument lists, and after ":" in dicts, but not before. |
| 128 | +* Put spaces around assignments and comparisons (except in argument lists). |
| 129 | +* No spaces just inside parentheses or just before argument lists. |
| 130 | +* No spaces just inside docstrings. |
| 131 | + |
| 132 | +Example: |
| 133 | + |
| 134 | +```python |
| 135 | +def make_squares(key, value=0): |
| 136 | + """! Return a dictionary and a list... |
| 137 | + @param value Value parameter with default value of zero (0) |
| 138 | + @return Retruns tuple of 'd' stuff and 'l' stuff |
| 139 | + """ |
| 140 | + d = {key: value} |
| 141 | + l = [key, value] |
| 142 | + return d, l |
| 143 | +``` |
| 144 | + |
| 145 | +### Naming |
| 146 | + |
| 147 | +* `joined_lower` for functions, methods, attributes. |
| 148 | +* `joined_lower` or ALL_CAPS for constants. |
| 149 | +* `StudlyCaps` for classes. |
| 150 | +* `camelCase` only to conform to pre-existing conventions. |
| 151 | +* Attributes: `interface`, `_internal`, `__private` |
| 152 | +* Try to avoid the `__private` form. |
| 153 | + |
| 154 | +## Testing and code coverage |
| 155 | + |
| 156 | +The application should be unit tested (at least a minimal set of unit tests should be implemented in the `/test` directory). We should be able to measure the unit test code coverage. |
| 157 | + |
| 158 | +Run a unit test suite to make sure your changes do not break current implementation: |
| 159 | + |
| 160 | +``` |
| 161 | +$ cd <package> |
| 162 | +$ python setup.py test |
| 163 | +``` |
| 164 | + |
| 165 | +## Code coverage |
| 166 | + |
| 167 | +To measure application code coverage for unit tests, please use the coverage tool. This set of commands locally creates a code coverage report for all unit tests: |
| 168 | + |
| 169 | +``` |
| 170 | +$ cd <package> |
| 171 | +$ coverage run setup.py test |
| 172 | +$ coverage report |
| 173 | +$ coverage html |
| 174 | +``` |
| 175 | + |
| 176 | +The last command generates an HTML code coverage report. You can use it to check which parts of your code are not unit tested. |
| 177 | + |
| 178 | +## Keep your GitHub fork updated |
| 179 | + |
| 180 | +To fork a GitHub repo SOME_REPO/appname to USER/appname and keep it updated, please use the following steps. |
| 181 | + |
| 182 | +### Track changes |
| 183 | + |
| 184 | +``` |
| 185 | +$ git clone [email protected]:USER/appname.git |
| 186 | +$ cd appname |
| 187 | +$ git remote add upstream [email protected]:SOME_REPO/appname.git |
| 188 | +``` |
| 189 | + |
| 190 | +### Verify: |
| 191 | + |
| 192 | +Verify with the following: |
| 193 | + |
| 194 | +``` |
| 195 | +$ git remote -v |
| 196 | +origin https://github.com/USER/appname.git (fetch) |
| 197 | +origin https://github.com/USER/appname.git (push) |
| 198 | +upstream https://github.com/SOME_REPO/appname.git (fetch) |
| 199 | +upstream https://github.com/SOME_REPO/appname.git (push) |
| 200 | +``` |
| 201 | + |
| 202 | +### Update |
| 203 | + |
| 204 | +To update, do the following from the local master branch: |
| 205 | + |
| 206 | +``` |
| 207 | +$ git fetch upstream |
| 208 | +$ git rebase upstream/master |
| 209 | +``` |
| 210 | + |
| 211 | +Rebasing creates a cleaner history for developers with local changes or commits. |
| 212 | + |
| 213 | +## Final notes |
| 214 | + |
| 215 | +1. Please do not change the version of the package in the `setup.py` file. The person or process responsible for releasing will do this and release the new version. |
| 216 | +2. Keep your GitHub fork updated! Please make sure you are rebasing your local branch with changes, so it is up to date and we can automatically merge your pull request. |
| 217 | +3. If possible, please squash your commits before pushing to the remote repository. |
| 218 | +4. Please, as part of your pull request: |
| 219 | + * Update `README.md` if your changes add new functionality to the module. |
| 220 | + * Add unit tests to the `/test` directory to cover your changes or new functionality. |
0 commit comments