From 4ff77ffc894bb1918feb270635b19da81735c818 Mon Sep 17 00:00:00 2001 From: "Martine S. Lenders" Date: Fri, 22 Nov 2019 17:28:11 +0100 Subject: [PATCH 1/5] CONTRIBUTING.md: copy "Help Wanted" section over from Wiki page Source: https://github.com/RIOT-OS/RIOT/wiki/Contributing-to-RIOT/8d2a6c8a0c744dcca6357e1a40d7bfeadf3ec31c#help-wanted --- CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a242e60d33..aa55f425bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,40 @@ As a reminder, all contributors are expected to follow our [riot-chat]: http://webchat.freenode.net?channels=riot-os +## 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](https://help.github.com/articles/using-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](https://github.com/RIOT-OS/RIOT/issues?state=open). 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. 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, a more detailed version is available [here](https://github.com/RIOT-OS/RIOT/wiki/Development-procedures)) + + 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](https://github.com/RIOT-OS/RIOT/blob/master/CODING_CONVENTIONS.md) + 1. Push this branch to your fork on GitHub + 1. Do a [pull request](https://help.github.com/articles/using-pull-requests) (Use the [[labels|Labels]]) + 1. Other RIOT members 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. + ## Feature Requests [feature-requests]: #feature-requests From 535950b35814dcf3de06db453e54c3bcb721bbf7 Mon Sep 17 00:00:00 2001 From: "Martine S. Lenders" Date: Fri, 22 Nov 2019 17:41:14 +0100 Subject: [PATCH 2/5] CONTRIBUTING.md: update "Help wanted" section for rest of the file --- CONTRIBUTING.md | 58 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa55f425bf..ac7be9a112 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,7 @@ 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: +* [Help wanted][help-wanted] * [Feature Requests][feature-requests] * [Bug Reports][bug-reports] * [Pull Requests][pull-requests] @@ -17,39 +18,70 @@ As a reminder, all contributors are expected to follow our [riot-chat]: http://webchat.freenode.net?channels=riot-os -## Help wanted +## 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. +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. +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](https://help.github.com/articles/using-pull-requests). +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. +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](https://github.com/RIOT-OS/RIOT/issues?state=open). 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. Their meanings are explained [[here|Labels]]. +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, a more detailed version is available [here](https://github.com/RIOT-OS/RIOT/wiki/Development-procedures)) +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](https://github.com/RIOT-OS/RIOT/blob/master/CODING_CONVENTIONS.md) + 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](https://help.github.com/articles/using-pull-requests) (Use the [[labels|Labels]]) - 1. Other RIOT members will provide feedback + 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. +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 From e4556f8f35ec7cac0d6c4f2c50752787ef3bb75a Mon Sep 17 00:00:00 2001 From: "Martine S. Lenders" Date: Fri, 22 Nov 2019 17:43:35 +0100 Subject: [PATCH 3/5] CONTRIBUTING.md: Add "Getting Started" section --- CONTRIBUTING.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac7be9a112..50c22318dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,7 @@ 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] * [Feature Requests][feature-requests] * [Bug Reports][bug-reports] @@ -18,6 +19,17 @@ 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 + ## Help Wanted [help-wanted]: #help-wanted In case you're not really sure where to start, we've created a list of suggestions. From 81dbab193e866cb164c671e7211d2aad6b8b4fd2 Mon Sep 17 00:00:00 2001 From: "Martine S. Lenders" Date: Fri, 22 Nov 2019 17:43:47 +0100 Subject: [PATCH 4/5] CONTRIBUTING.md: Add "General Tips" section --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50c22318dd..9d88d6839b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ 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] @@ -30,6 +31,27 @@ If you are just beginning to work with RIOT you might first want to read our [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. From 7aae27de034ce3eb765b4b63db415c92b4871d49 Mon Sep 17 00:00:00 2001 From: "Martine S. Lenders" Date: Fri, 22 Nov 2019 17:44:05 +0100 Subject: [PATCH 5/5] CONTRIBUTING.md: Add help for resolving a pull request --- CONTRIBUTING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d88d6839b..8f5beb9d5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -354,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: