diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc2c17ab7d..42b9988ee0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,9 @@ 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: +* [Getting Started][getting-started] +* [Help wanted][help-wanted] +* [General Tips][general-tips] * [Feature Requests][feature-requests] * [Bug Reports][bug-reports] * [Pull Requests][pull-requests] @@ -17,6 +20,103 @@ As a reminder, all contributors are expected to follow our [riot-chat]: http://webchat.freenode.net?channels=riot-os +## Getting Started +[getting-started]: #getting-started +If you are just beginning to work with RIOT you might first want to read our +[documentation]. Especially the following sections might be of interest to you + +- [Getting Started](https://doc.riot-os.org/getting-started.html) +- [Creating modules](https://doc.riot-os.org/creating-modules.html) +- [Creating an application](https://doc.riot-os.org/creating-an-application.html) + +[documentation]: https://doc.riot-os.org + +## General Tips +[general-tips]: #general-tips +From experience, the following recommendations help to get a software +contribution into RIOT master faster: + +- **Ask around for help!** Either offline or through one of our communication + channels (see above). The earlier you check your feature design with other + people, the less likely it is that it is denied during the review process. +- **Verify your concept early!** If you work on your own until the code + *looks* good enough to show publicly, you might miss some design flaws others + might have spotted earlier. +- **Keep it simple!** Try to use what is already there and don't change existing + APIs if not absolutely necessary. +- **Keep it small!** A PR with >1000 lines of changes will very likely make + even the most active reviewer put your review on their long to-do list. +- **Keep it modular!** Make extensions to a feature or new features for a + platform optionally to use. +- **Provide tests!** They should be comprehensible and easy to be executed. + Alternatively comprehensive testing procedures should be provided with your + pull request. + +## Help Wanted +[help-wanted]: #help-wanted +In case you're not really sure where to start, we've created a list of suggestions. + +### Documentation +If you've found yourself struggling to understand a particular aspect, chances +are you're not the first and won't be the last. Writing down what you've learned +is a great way to recap your new knowledge and share it with others. You can +also start to learn about RIOT by combing through existing documentation and +fixing errors and typos. Any help with improving the documentation is greatly +appreciated and makes a big difference to the RIOT project. +After you've finished writing, please publish your documentation in one of the +following ways, depending on its type. + +#### General knowledge, HOWTOs +Articles that focus on design aspects or how to use a particular module should +be contributed to the [RIOT wiki](https://github.com/RIOT-OS/RIOT/wiki). After +you've added your entry, please share it on the riot-dev mailing list so +everyone is aware of its existence (and thank you). +If you'd like to document a solution to minor annoyances or common pitfalls, +please do not hesitate to extend the [Troubleshooting wiki +page](https://github.com/RIOT-OS/RIOT/wiki/Troubleshooting). Again, please share +your additions with the riot-dev mailing list. + +#### Code comments, HOWTOs for particular projects +Documentation that relates directly to the code at hand like the HOWTO files +that can be found in some of the directories in ``RIOT/examples/`` or comments +in the code itself should be submitted through a [pull request][pull-requests]. + +If you're not sure about the correct way to submit your writing, please ask on +the mailing list or open an issue saying which documentation is missing. The +other RIOTers will help you find the right format. + +### Issues +If RIOT behaves oddly, please do not hesitate to [open an issue][open-an-issue]. +Other RIOT developers will be happy to help figure out what the problem is and +fix possible bugs. Please notice that we use a bunch of tags to label the +issues. If you have permission to use them, do it. Their meanings are explained +[here][labels]. + +### Contribute code +If you think your work should be integrated in the main RIOT repository, take +the following steps: (short version, the more detailed version can be found +[below][pull-requests]) + + 0. Fork the RIOT git repository (if you haven't done this already) + 1. Create a branch + 2. Make commits + 3. Make sure your code is in compliance with RIOTs + [coding conventions][coding-conventions] + 1. Push this branch to your fork on GitHub + 1. Do a [pull request][open-a-pull-request] (use the [labels] if you have + permission to use them) + 1. RIOT maintainers will provide feedback + 1. Address this feedback + 1. Your code is merged in RIOT master branch + +If you do not receive feedback after a reasonable time, feel free to address +maintainers directly. This is especially true if you addressed previous feedback +and got no response. + +[open-an-issue]: https://github.com/RIOT-OS/RIOT/issues?q=state:open+type:issue+label:"Type:+bug" +[labels]: https://github.com/RIOT-OS/RIOT/wiki/RIOT%27s-labeling-system +[open-a-pull-request]: https://help.github.com/articles/using-pull-requests + ## Feature Requests [feature-requests]: #feature-requests @@ -254,6 +354,20 @@ 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. +If you encounter a merge conflict you could either resolve it by hand with an +editor and use + + $ git add -p + +To add your changes or use a merge tool like [meld](https://meldmerge.org/) to +resolve your merge conflict. + + $ git mergetool + +After the merge conflict is resolved you can continue to rebase by using + + $ git rebase --continue + Once squashing is done, you will have to force push your branch to update the PR: