mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
Merge pull request #12786 from miri64/contributing/enh/wiki+tips
CONTRIBUTING.md: migrate parts of wiki and add general tips
This commit is contained in:
commit
22db0d9ed4
114
CONTRIBUTING.md
114
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
|
contribute, and we appreciate all of them. You can jump to the major sections
|
||||||
of this document using the following links:
|
of this document using the following links:
|
||||||
|
|
||||||
|
* [Getting Started][getting-started]
|
||||||
|
* [Help wanted][help-wanted]
|
||||||
|
* [General Tips][general-tips]
|
||||||
* [Feature Requests][feature-requests]
|
* [Feature Requests][feature-requests]
|
||||||
* [Bug Reports][bug-reports]
|
* [Bug Reports][bug-reports]
|
||||||
* [Pull Requests][pull-requests]
|
* [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
|
[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]: #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
|
you introduce regression and won't be able to recover them from previous
|
||||||
commits.
|
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
|
Once squashing is done, you will have to force push your branch to update the
|
||||||
PR:
|
PR:
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user