From 7a9aa7306dbc28b53c5d4faad07fc5c4892520d3 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 14:24:10 +0200 Subject: [PATCH 1/9] CONTRIBUTING: link to both IRC and Matrix Link to both the IRC and Matrix end of the chat, as both are used. --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42b9988ee0..4a084ef11f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,13 +12,15 @@ of this document using the following links: * [Pull Requests][pull-requests] * [Writing Documentation][writing-documentation] -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]. + +If you have questions, please send an email to or + mailing list or chat on `#riot-os` on [IRC] or [Matrix]. As a reminder, all contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). -[riot-chat]: http://webchat.freenode.net?channels=riot-os +[IRC]: http://webchat.freenode.net?channels=riot-os +[Matrix]: https://matrix.to/#/#riot-os:matrix.org ## Getting Started [getting-started]: #getting-started From 456ae110ed00624f157134438f72ad8ee23543a2 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 14:26:53 +0200 Subject: [PATCH 2/9] CONTRIBUTING: replace 'help wanted' by 'contributing code' The naming of the 'help wanted' section is unclear, and unhelpful. Additionally, most of the items listed in it are not actually part of the contribution process: - While *Documentation* is welcome, it is not helpful to document the kinds in the contributing document. The contributing document should document *how*, not *what*. - The *Issues* section is out of place: I doubt anyone will look at the *contributing guidelines* to find out how to open an issue. The content is also pretty self-explanatory. - What's left is only 'Contributing Code', so promote it! --- CONTRIBUTING.md | 45 +++------------------------------------------ 1 file changed, 3 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a084ef11f..9589c5a2cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ 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] +* [Contributing code][contributing-code] * [General Tips][general-tips] * [Feature Requests][feature-requests] * [Bug Reports][bug-reports] @@ -54,47 +54,8 @@ contribution into RIOT master faster: 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 +## Contributing code +[contributing-code]: #contributing-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]) From 1e9ba0d0cb69764733e1c19473c76dc7659e989c Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 14:30:59 +0200 Subject: [PATCH 3/9] CONTRIBUTING: remove 'feature request' and 'bug reports' sections These have fairly clear templates in the GitHub interface. Duplicating that here servers no purpose. --- CONTRIBUTING.md | 87 +++++++++++++++---------------------------------- 1 file changed, 27 insertions(+), 60 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9589c5a2cc..c19e982341 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,14 +5,13 @@ 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] +* [Bug Reports and Feature Requests][issues] +* [General Tips][general-tips] * [Contributing code][contributing-code] * [General Tips][general-tips] -* [Feature Requests][feature-requests] -* [Bug Reports][bug-reports] * [Pull Requests][pull-requests] * [Writing Documentation][writing-documentation] - If you have questions, please send an email to or mailing list or chat on `#riot-os` on [IRC] or [Matrix]. @@ -33,6 +32,31 @@ If you are just beginning to work with RIOT you might first want to read our [documentation]: https://doc.riot-os.org +## Bug reports and feature requests +[issues]: #bug-reports-and-feature-requests +Both bug reports and feature request, big or small, are welcome. + +Before submitting a feature request, please check if an [open issue][existing-feature-request] +already exists. If this is not the case, [submit a feature request][feature-request]. +Describe your use case, why you need this feature and why this feature is important for RIOT. + +Before filing a bug report, please check if an [open issue][existing-bug] +already exists. If this is not the case, [submit a new bug report][bug-report]. +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 **. +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. + +[bug reports]: https://github.com/RIOT-OS/RIOT/issues/new?template=bug_report.md +[feature requests]: https://github.com/RIOT-OS/RIOT/issues/new?template=feature_request.md + +[existing-feature-request]: https://github.com/RIOT-OS/RIOT/issues?q=state:open+type:issue+label:"Type:+new+feature" +[feature-request]: https://github.com/RIOT-OS/RIOT/issues/new?template=feature_request.md&title=Feature+Request: +[existing-bug]: https://github.com/RIOT-OS/RIOT/issues?q=state:open+type:issue+label:"Type:+bug" +[bug-report]: https://github.com/RIOT-OS/RIOT/issues/new?template=bug_report.md&title=Bug: + ## General Tips [general-tips]: #general-tips From experience, the following recommendations help to get a software @@ -80,63 +104,6 @@ and got no response. [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 - -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 the bug you have found hasn't been reported, 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: -``` -make print-versions -``` - -In summary, try to include as much information as possible to help maintainers -or other developers fix the bug quickly. - ## Pull Requests [pull-requests]: #pull-requests From 16bee2046a87ff21dc59b32338be8b93210d5447 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 14:34:55 +0200 Subject: [PATCH 4/9] CONTRIBUTING: reorganize 'contributing code' and 'pull request' Having two lists that need to be read thouroughly for pull requests is unclear. Clean this up by: - Splitting the *pull request* steps into *coding conventions*, *commit conventions*, and *pull requests* - Completing the contribution steps with references to those sections. - Reordering all steps to any contributor will encounter them in order. - Rename and promote 'Git usage', to a 'Working with Git' section. This is then referred to at the start of the document and in the contribution steps. --- CONTRIBUTING.md | 145 +++++++++++++++++++++++------------------------- 1 file changed, 68 insertions(+), 77 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c19e982341..5ef4295445 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,9 +8,8 @@ of this document using the following links: * [Bug Reports and Feature Requests][issues] * [General Tips][general-tips] * [Contributing code][contributing-code] -* [General Tips][general-tips] -* [Pull Requests][pull-requests] * [Writing Documentation][writing-documentation] +* [Working with Git][working with git] If you have questions, please send an email to or mailing list or chat on `#riot-os` on [IRC] or [Matrix]. @@ -81,79 +80,29 @@ contribution into RIOT master faster: ## Contributing code [contributing-code]: #contributing-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]) +the following steps: - 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. + 1. Fork the RIOT git repository (if you haven't done this already). + 1. Create a branch for your contribution. + 1. Make sure your code is in compliance with RIOTs [coding conventions]. + 1. Make commits. Make sure to follow RIOTs [commit conventions]. + 1. Push this branch to your fork on GitHub. + 1. Open a [pull request][open-a-pull-request]. See [pull requests]. + 1. RIOT maintainers will set [labels] and provide feedback. + 1. Address this feedback. See [working with git]. + 1. Your code is merged in RIOT master branch when it passes review. [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 -## Pull Requests -[pull-requests]: #pull-requests +### Coding conventions +[coding conventions]: #coding-conventions -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. +RIOT has extensive [coding conventions][coding-conventions]. +It is possible to check if your code follows these conventions: -[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. Include closed PR's in your - search, as previous work might have been closed for lack of interest. - 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 there to help - maintainers understand your contribution and help them in 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: +* You can [uncrustify] `.c` and `.h` files: $ uncrustify -c $RIOTBASE/uncrustify-riot.cfg @@ -168,16 +117,54 @@ into the source repository. Use it before opening a PR to perform last time checks. +[coding-conventions]: CODING_CONVENTIONS.md + +### Commit conventions +[commit conventions]: #commit-conventions + * Each commit should target changes of specific parts/modules of RIOT. The commits use the following pattern: - `area of code: description of changes`. + 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. +### 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. + +* 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. Include closed PR's in your + search, as previous work might have been closed for lack of interest. + 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. + +* The Pull Request title should reflect what it is about and be in the form: + + area of change: description of changes + +* Each Pull Request form uses a template that is there to help + maintainers understand your contribution and help them in testing it. + Please fill each section with as much information as possible. + +* 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. + +* 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. * 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 @@ -187,17 +174,21 @@ into the source repository. area of the PR. You can also advertise the PR on devel@riot-os.org mailing list and ask for a review there. +* Try to answer reviews as quickly as possible to speed up the review process + and avoid stalled PRs. + You can find more information about RIOT development procedure on this [wiki page][development-procedures]. +[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 [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]: CODING_CONVENTIONS.md [uncrustify]: http://uncrustify.sourceforge.net [development-procedures]: https://github.com/RIOT-OS/RIOT/wiki/Development-procedures -### Git usage - +## Working with Git +[working with git]: #working-with-git 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]. @@ -208,7 +199,7 @@ 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 +### 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]. @@ -234,7 +225,7 @@ also that it is up-to-date with the upstream repository. [riot-github]: https://github.com/RIOT-OS/RIOT -#### Work on branches +### 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 @@ -246,7 +237,7 @@ from it. # Do your changes, commit, update with latest upstream master $ git push -#### Add fixup commits during review +### 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. @@ -260,7 +251,7 @@ you can use the `--fixup` option: $ git add /path/of/prefix2 $ git commit --fixup -#### Squash commits after review +### Squash commits after review Squashing a commit is done using the rebase subcommand of git in interactive mode: From 1cadc951429be7e41c407448107c9b4524cdc112 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 14:41:02 +0200 Subject: [PATCH 5/9] CONTRIBUTING: move the 'writing documentation' section Because the *working with git* section is quite long, it obscures the *writing documentation* section. Move it to before the *working with git* section. --- CONTRIBUTING.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ef4295445..fac0a92e60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -187,6 +187,28 @@ You can find more information about RIOT development procedure on this [uncrustify]: http://uncrustify.sourceforge.net [development-procedures]: https://github.com/RIOT-OS/RIOT/wiki/Development-procedures +## 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 the following +from the base directory of the RIOT source code. + + + $ make doc + +The generated documentation is located in `doc/doxygen/html` + +[doxygen]: http://www.doxygen.nl/ + ## Working with Git [working with git]: #working-with-git Using git is a bit difficult for newcomers. If you are completely new to git, @@ -293,25 +315,3 @@ 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/ From a34cba33078781ed0a9a112890c95a5629e97676 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 15:16:27 +0200 Subject: [PATCH 6/9] CONTRIBUTING: add example commit Add an example commit to the *commit conventions* section. Refer to this in the pull request steps. --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fac0a92e60..a1f4d76dc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -129,6 +129,13 @@ It is possible to check if your code follows these conventions: You can use multi-line commit messages if you want to detail more the changes. + For example: + + periph/timer: Document that set_absolute is expected to wrap + + Most timers are implemented this way already, and keeping (documenting) + it that way allows the generic timer_set implementation to stay as + simple as it is. ### Pull Requests [pull requests]: #pull-requests @@ -148,9 +155,8 @@ into the source repository. 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. -* The Pull Request title should reflect what it is about and be in the form: - - area of change: description of changes +* The Pull Request title should reflect what it is about and be in the same form + as the [commit conventions]. * Each Pull Request form uses a template that is there to help maintainers understand your contribution and help them in testing it. From ef92773f99fd46af9b30c7bf58215a090861aeaf Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 15:24:19 +0200 Subject: [PATCH 7/9] CONTRIBUTING: change code block style Change the code blocks to triple-backtick (` ``` `) style in order to 1) provide a consistent indent and 2) enable syntax highlighting. --- CONTRIBUTING.md | 91 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 63 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1f4d76dc1..1a664e34e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,7 +104,9 @@ It is possible to check if your code follows these conventions: * You can [uncrustify] `.c` and `.h` files: - $ uncrustify -c $RIOTBASE/uncrustify-riot.cfg + ```console + $ uncrustify -c $RIOTBASE/uncrustify-riot.cfg + ``` * RIOT provides static test tools to verify the quality of changes (cppcheck, trailing whitespaces, documentation, etc). These tools are wrapped in a @@ -113,7 +115,9 @@ It is possible to check if your code follows these conventions: *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 + ```console + $ make static-test + ``` Use it before opening a PR to perform last time checks. @@ -125,17 +129,21 @@ It is possible to check if your code follows these conventions: * Each commit should target changes of specific parts/modules of RIOT. The commits use the following pattern: - area of code: description of changes + ``` + area of code: description of changes + ``` You can use multi-line commit messages if you want to detail more the changes. For example: - periph/timer: Document that set_absolute is expected to wrap - - Most timers are implemented this way already, and keeping (documenting) - it that way allows the generic timer_set implementation to stay as - simple as it is. + ``` + periph/timer: Document that set_absolute is expected to wrap + + Most timers are implemented this way already, and keeping (documenting) + it that way allows the generic timer_set implementation to stay as + simple as it is. + ``` ### Pull Requests [pull requests]: #pull-requests @@ -208,8 +216,9 @@ General documentation pages are written in Markdown and located in To generate the documentation, simply run the following from the base directory of the RIOT source code. - - $ make doc +```console +$ make doc +``` The generated documentation is located in `doc/doxygen/html` @@ -234,19 +243,25 @@ 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 = "" - $ git config --global user.email = "" +```console +$ git config --global user.name = "" +$ git config --global user.email = "" +``` Then clone locally your fork of RIOT (replace `account name` with your actual login on GitHub): - $ git clone git@github.com:/RIOT.git +```console +$ git clone git@github.com:/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 - $ git pull --rebase https://github.com/RIOT-OS/RIOT.git +```console +$ git checkout +$ 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. @@ -259,11 +274,17 @@ 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 - # Do your changes, commit, update with latest upstream master - $ git push +```console +$ git checkout master +$ git pull --rebase https://github.com/RIOT-OS/RIOT.git +$ git checkout -b +``` + +Do your changes, commit, update with latest upstream master + +```console +$ git push +``` ### Add fixup commits during review @@ -276,15 +297,19 @@ Let's say your PR contains 3 commits with comments: `prefix1: change 1`, 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 +```console +$ git add /path/of/prefix2 +$ git commit --fixup +``` ### Squash commits after review Squashing a commit is done using the rebase subcommand of git in interactive mode: - $ git rebase master -i +```console +$ git rebase master -i +``` You can find information on rebasing in [GitHub rebase documentation][about-git-rebase]. @@ -294,7 +319,9 @@ You can find information on rebasing in 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 +```console +$ git rebase -i --autosquash +``` **Watch out: Don't squash your commit until a maintainer asks you to do it.** @@ -306,18 +333,26 @@ commits. If you encounter a merge conflict you could either resolve it by hand with an editor and use - $ git add -p +```console +$ git add -p +``` To add your changes or use a merge tool like [meld](https://meldmerge.org/) to resolve your merge conflict. - $ git mergetool +```console +$ git mergetool +``` After the merge conflict is resolved you can continue to rebase by using - $ git rebase --continue +```console +$ git rebase --continue +``` Once squashing is done, you will have to force push your branch to update the PR: - $ git push --force-with-lease +```console +$ git push --force-with-lease +``` From 7e57cf2c8f8026aca7c93e5b26e92b01d6ccb41b Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sat, 3 Oct 2020 15:41:17 +0200 Subject: [PATCH 8/9] CONTRIBUTING: add --no-backup to uncrustify --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a664e34e6..910db5fcc7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,9 +105,12 @@ It is possible to check if your code follows these conventions: * You can [uncrustify] `.c` and `.h` files: ```console - $ uncrustify -c $RIOTBASE/uncrustify-riot.cfg + $ uncrustify -c $RIOTBASE/uncrustify-riot.cfg --no-backup ``` + **Note**: The `--no-backup` flag makes uncrustify *replace* the current file + with a formatted version. + * 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`. From 00e7fae25b5d461e6f1e123cf2b409823cdcf990 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Sun, 4 Oct 2020 17:20:44 +0200 Subject: [PATCH 9/9] CONTRIBUTING: move 'general tips' under 'contributing code' The general tips all apply to code contributions. As such, move them to the right section. --- CONTRIBUTING.md | 45 +++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 910db5fcc7..388b66e976 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,6 @@ of this document using the following links: * [Getting Started][getting-started] * [Bug Reports and Feature Requests][issues] -* [General Tips][general-tips] * [Contributing code][contributing-code] * [Writing Documentation][writing-documentation] * [Working with Git][working with git] @@ -56,8 +55,29 @@ public channels, to allow us adequate time to release the fix. [existing-bug]: https://github.com/RIOT-OS/RIOT/issues?q=state:open+type:issue+label:"Type:+bug" [bug-report]: https://github.com/RIOT-OS/RIOT/issues/new?template=bug_report.md&title=Bug: -## General Tips -[general-tips]: #general-tips +## Contributing code +[contributing-code]: #contributing-code +If you think your work should be integrated in the main RIOT repository, take +the following steps: + + 1. Fork the RIOT git repository (if you haven't done this already). + 1. Create a branch for your contribution. + 1. Make sure your code is in compliance with RIOTs [coding conventions]. + 1. Make commits. Make sure to follow RIOTs [commit conventions]. + 1. Push this branch to your fork on GitHub. + 1. Open a [pull request][open-a-pull-request]. See [pull requests]. + 1. RIOT maintainers will set [labels] and provide feedback. + 1. Address this feedback. See [working with git]. + 1. Your code is merged in RIOT master branch when it passes review. + +Be sure to read the [general tips] below. + +[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 + +### General Tips +[general tips]: #general-tips From experience, the following recommendations help to get a software contribution into RIOT master faster: @@ -77,25 +97,6 @@ contribution into RIOT master faster: Alternatively comprehensive testing procedures should be provided with your pull request. -## Contributing code -[contributing-code]: #contributing-code -If you think your work should be integrated in the main RIOT repository, take -the following steps: - - 1. Fork the RIOT git repository (if you haven't done this already). - 1. Create a branch for your contribution. - 1. Make sure your code is in compliance with RIOTs [coding conventions]. - 1. Make commits. Make sure to follow RIOTs [commit conventions]. - 1. Push this branch to your fork on GitHub. - 1. Open a [pull request][open-a-pull-request]. See [pull requests]. - 1. RIOT maintainers will set [labels] and provide feedback. - 1. Address this feedback. See [working with git]. - 1. Your code is merged in RIOT master branch when it passes review. - -[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 - ### Coding conventions [coding conventions]: #coding-conventions