diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 868b6de67722215ad4464bd2234989621afccaa6..580ec6d9fcc05110f6826f8a749b53531bf1020a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,281 @@ -# CONTRIBUTE -This is a short version of the [Development Procedures](https://github.com/RIOT-OS/RIOT/wiki/Development-procedures). +# Contributing to RIOT -1. Check if your code follows the [coding conventions](https://github.com/RIOT-OS/RIOT/wiki/Coding-conventions). If the code does not comply these style rules, your code will not be merged. +Thank you for your interest in contributing to RIOT! There are many ways to +contribute, and we appreciate all of them. You can jump to the major sections +of this document using the following links: -2. The master branch should always be in a working state. The RIOT maintainers will create release tags based on this branch, whenever a milestone is completed. +* [Feature Requests][feature-requests] +* [Bug Reports][bug-reports] +* [Pull Requests][pull-requests] +* [Writing Documentation][writing-documentation] -3. Comments on a pull request should be added to the request itself, and *not* to the commit. +If you have questions, please send an email to users@riot-os.org or +devel@riot-os.org mailing list or chat on [#riot-os][riot-chat]. -4. Keep commits to the point, e.g., don't add whitespace/typo fixes to other code changes. If changes are layered, layer the patches. +As a reminder, all contributors are expected to follow our +[Code of Conduct](CODE_OF_CONDUCT.md). -5. Describe the technical detail of the change(s) as specific as possible. +[riot-chat]: http://webchat.freenode.net?channels=riot-os -6. Use [Labels](https://github.com/RIOT-OS/RIOT/wiki/Labels) to help classify pull requests and issues. +## Feature Requests +[feature-requests]: #feature-requests -7. Please adhere to our [code of conduct](https://github.com/RIOT-OS/RIOT/blob/master/CODE_OF_CONDUCT.md) +Before opening a new feature request, check the +[existing feature requests][existing-feature-request] if there's one already +open on the same topic. + +To request new features or enhancements, just open a new +[feature request issue][new-feature-request]. Describe your use case, why you +need this feature and why this feature is important for RIOT. + +[existing-feature-request]: https://github.com/RIOT-OS/RIOT/issues?q=state:open+type:issue+label:"Type:+new+feature" +[new-feature-request]: https://github.com/RIOT-OS/RIOT/issues/new?template=feature_request.md&title=Feature+Request: + +## Bug Reports +[bug-reports]: #bug-reports + +While bugs are unfortunate, they're a reality in software. We can't fix what we +don't know about, so please report liberally. If you're not sure if something +is a bug or not, feel free to file a bug report anyway. + +**If you believe reporting your bug publicly represents a security risk to +RIOT users, please send an email describing the bug to security@riot-os.org**. +We would appreciate waiting for a 6 months grace period before reporting it on +public channels, to allow us adequate time to release the fix. + +Before reporting a bug, have a look at [open bugs][existing-bugs-link]. Maybe +someone has already reported your error. + +Once you have verified that they haven't, opening an issue is as easy as +clicking on [this link][bug-report-link] and filling out the fields. + +[existing-bugs-link]: https://github.com/RIOT-OS/RIOT/issues?q=state:open+type:issue+label:"Type:+bug" +[bug-report-link]: https://github.com/RIOT-OS/RIOT/issues/new?template=bug_report.md&title=Bug: + +Each bug report issue uses a template with 5 sections that are there to help +other contributors understand your issue and eventually reproduce it: + + #### Description + + #### Steps to reproduce the issue + + #### Expected results + + #### Actual results + + #### Versions + +To fill the `Versions` section, you can use the script provided in the RIOT git +repository: +``` +./dist/tools/ci/print_toolchain_versions.sh +``` + +In summary, try to include as much information as possible, to help maintainers +or other developers to fix the bug quickly. + +## Pull Requests +[pull-requests]: #pull-requests + +GitHub's Pull Request (PR) feature is the primary mechanism used to make +contributions to the RIOT codebase. GitHub itself has some great documentation +on [using the Pull Request feature][about-pull-requests]. +We use the [fork and pull model][development-models], where contributors push +changes to their personal fork and create pull requests to bring those changes +into the source repository. + +[about-pull-requests]: https://help.github.com/articles/about-pull-requests/ +[development-models]: https://help.github.com/articles/creating-a-pull-request-from-a-fork + +### General rules + +* Before opening a new Pull Request, have a look at + [existing ones][existing-pull-requests]. Maybe someone has already opened one + about the same thing. If it's the case, you might be able to help with the + contribution. Just comment on the PR and ask. + Old and stalled [PRs are sometimes archived][archived-pull-requests] with the + "State: archived" label, maybe one of them is also about the same topic. + +* Each Pull Request form uses a template with 3 sections that are here to help + maintainers understand your contribution and help them testing it: + + #### Contribution description + + #### Testing procedure + + #### Issues/PRs references + + Please fill each section with as much information as possible. + +* The Pull Request title should reflect what it is about and be in the form: + + `area of change: description of changes` + +* Remember that smaller PRs tend to be merged faster, so keep your changes as + concise as possible. They should be confined to a single explainable + change, and be runnable on their own. So don't hesitate to split your PRs + into smaller ones when possible. + +* In the Pull Request form, we recommend that you leave the + "Allow edits from maintainers" check box ticked. This will allow maintainer + finalizing your PR by pushing in your branch. In general, this speeds up the + PR merge in the main repository. Note that this is not an obligation. + +* Check if your code follows the [coding conventions][coding-conventions]. If + it doesn't, you can [uncrustify][uncrustify] a file: + + $ uncrustify -c $RIOTBASE/uncrustify-riot.cfg <your file> + +* RIOT provides static test tools to verify the quality of changes (cppcheck, + trailing whitespaces, documentation, etc). These tools are wrapped in a + single `make` target: `static-test`. + + *Watch out:* the command below will rebase your branch on your master branch, + so make sure they can be rebased (e.g. there's no potential conflict). + + $ make static-test + + Use it before opening a PR to perform last time checks. + +* Each commit should target changes of specific parts/modules of RIOT. The + commits use the following pattern: + + `area of code: description of changes`. + + You can use multi-line commit messages if you want to detail more the + changes. + +* Try to answer reviews as quickly as possible to speed up the review process + and avoid stalled PRs. + +* Maintainers try their best to review every PR as fast as possible, but they + are also only human and it can happen that they miss a few PRs or might be + preoccupied with other PRs. If it happens that your PR receive no review for + a long time, don't hesitate to gently solicit a review by commenting or + by explicitly mentioning a maintainer that you know is knowledgeable in the + area of the PR. You can also advertise the PR on devel@riot-os.org mailing + list and ask for a review there. + +You can find more information about RIOT development procedure on this +[wiki page][development-procedures]. + +[existing-pull-requests]: https://github.com/RIOT-OS/RIOT/pulls +[archived-pull-requests]: https://github.com/RIOT-OS/RIOT/pulls?q=is:pr+label:"State:+archived" +[coding-conventions]: https://github.com/RIOT-OS/RIOT/wiki/Coding-conventions +[uncrustify]: http://uncrustify.sourceforge.net +[development-procedures]: https://github.com/RIOT-OS/RIOT/wiki/Development-procedures + +### Git usage + +Using git is a bit difficult for newcomers. If you are completely new to git, +we recommend that you [start by learning it][try-github-io] a bit. You can also +read the official [getting started documentation][git-scm-getting-started]. + +In this section, we give the bare minimum for a better experience with our +development workflow on GitHub. + +[try-github-io]: https://try.github.io/ +[git-scm-getting-started]: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics + +#### Setup your local RIOT repository + +Before you start modifying code, you need to fork the RIOT upstream repository +from the [RIOT main GitHub page][riot-github]. + +If it's your first time with git, configure your name and emails: + + $ git config --global user.name = "<your name here>" + $ git config --global user.email = "<your email address here>" + +Then clone locally your fork of RIOT (replace `account name` with your actual +login on GitHub): + + $ git clone git@github.com:<account name>/RIOT.git + +You can keep any branch of your local repository up-to-date with the upstream +master branch with the following commands: + + $ git checkout <branch name> + $ git pull --rebase https://github.com/RIOT-OS/RIOT.git + +Use it before opening a PR. This will at least ensure the PR is mergeable but +also that it is up-to-date with the upstream repository. + +[riot-github]: https://github.com/RIOT-OS/RIOT + +#### Work on branches + +Avoid opening PR from the `master` branch of your fork to the master branch of +the RIOT upstream repository: update your master branch and start a new branch +from it. + + $ git checkout master + $ git pull --rebase https://github.com/RIOT-OS/RIOT.git + $ git checkout -b <new branch> + # Do your changes, commit, update with latest upstream master + $ git push + +#### Add fixup commits during review + +To keep the history of changes easier to track for reviewers, it is recommended +to push your review request updates in fixup commits. + +Let's say your PR contains 3 commits with comments: `prefix1: change 1`, +`prefix2: change 2` and `prefix3: change 3`. + +Instead of committing changes in `prefix2` in a 4th commit `prefix2: change 4`, +you can use the `--fixup` option: + + $ git add /path/of/prefix2 + $ git commit --fixup <prefix2 commit hash> + +#### Squash commits after review + +Squashing a commit is done using the rebase subcommand of git in interactive +mode: + + $ git rebase master -i + +You can find information on rebasing in +[GitHub rebase documentation][about-git-rebase]. + +[about-git-rebase]: https://help.github.com/articles/about-git-rebase/ + +If you used [fixup commits](#add-fixup-commits-during-review) during the review +phase, squashing commits can be performed in a single command: + + $ git rebase -i --autosquash + +**Watch out: Don't squash your commit until a maintainer asks you to do it.** + +Otherwise the history of review changes is lost and for large PRs, it +makes it difficult for the reviewer to follow them. It might also happen that +you introduce regression and won't be able to recover them from previous +commits. + +Once squashing is done, you will have to force push your branch to update the +PR: + + $ git push --force-with-lease + +## Writing Documentation +[writing-documentation]: #writing-documentation + +Documentation improvements are always welcome and a good starting point for +new contributors. This kind of contribution is merged quite quickly in general. + +RIOT documentation is built with [doxygen][doxygen]. Doxygen is configured to +parse header (.h) and `doc.txt` files in the RIOT source code to generate +the modules, cpus, boards and packages documentation. +General documentation pages are written in Markdown and located in +`doc/doxygen/src`. + +To generate the documentation, simply run: + + $ make doc + +from the base directory of the RIOT source code. + +The generated documentation is located in `doc/doxygen/html` + +[doxygen]: http://www.doxygen.nl/ diff --git a/README.md b/README.md index 6da550d504fb3f5fdbf9a0eba6b2c1f25298a4d0..812cb35e0f77d3813cad6b698e56582c3e86302d 100644 --- a/README.md +++ b/README.md @@ -94,9 +94,8 @@ To create a bridge and two (or `count` at your option) tap interfaces: ## CONTRIBUTE -To contribute something to RIOT, please refer to the [development -procedures](https://github.com/RIOT-OS/RIOT/wiki/Development-procedures) and -read all notes for best practice. +To contribute something to RIOT, please refer to our +[contributing document](CONTRIBUTING.md). ## MAILING LISTS * RIOT OS kernel developers list