From 3cb719239509f35fa1436a112d880a8059231e10 Mon Sep 17 00:00:00 2001 From: Simon Duquennoy Date: Sun, 29 Oct 2017 08:55:23 +0100 Subject: [PATCH] CONTRIBUTING.md: link to wiki where the content has moved --- CONTRIBUTING.md | 279 +----------------------------------------------- 1 file changed, 2 insertions(+), 277 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ed3d23a6..b6fb5d01f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,278 +1,3 @@ -Code Contributions -================== - -Do you have a new cool feature that you'd like to contribute to -Contiki? Or a fix for a bug? Great! The Contiki project loves code -contributions, improvements, and bugfixes, but we require that they -follow a set of guidelines and that they are contributed in a specific -way. - -Additional rules apply for contributions of a new hardware platform. - -General Advice --------------- - -The chance of getting your pull request accepted increases considerably -if you adhere to the following rules in addition to the aforementioned -formatting and naming standards: - -* Ensure that all contributed files have a valid copyright statement - and an open-source license. -* Do not bundle commits that are unrelated to each other -- create - separate pull requests instead. -* Adhere to ISO C99 in all C language source files. Exceptions are - allowed for those platform-dependent source files that rely on the - extensions of a specific set of compilers. -* Clean up the commit history. "git rebase -i" is useful for this purpose. -* Do not include executable binary files, because they are usually - rejected for security reasons. Instead, provide instructions for how - to compile the file, so that a trusted member of the merge team can - commit it. -* Write a descriptive pull request message. Explain the advantages and - disadvantages of your proposed changes. -* Before starting to work on a major contribution, discuss your idea - with experienced Contiki programmers (e.g., on the contiki-developers - mailing list) to avoid wasting time on things that have no chance of - getting merged into Contiki. - -Source code that goes into the mainline Contiki repository must be of -interest to a large part of the Contiki community. It must be -well-tested and the merge team must have confidence that the code can -be maintained over a longer period. See below for more details -pertaining to platform contributions. - -Contributions that have been made in research projects, and typically -do not get maintained thereafter, are better suited for inclusion in -the Contiki projects repository. - -Structuring Commits -------------------- - -* Write descriptive commit messages. They don't have to be very long, - but you should mention what the commit achieves. Commit messages - like "modified foo/bar.c" are not helpful, should not be used, and - are likely to result in you having to re-write them. -* Please do not add / remove irrelevant new line markers. Don't remove - the new line marker at the EOF. -* Please, make sure that your patch doesn't add lines with trailing - whitespaces. If you run uncrustify as discussed above, this should - get taken care of for you automatically. -* More generally speaking, make sure that each commit in your history - only includes changes necessary to implement whatever it is the - commit is trying to achieve. All changes should be mentioned in the - commit message. - -Code Formatting ---------------- - -We require that all code contributed to the Contiki tree follows the -same code formatting as the existing Contiki code. We are very strict -on this. - -Code must be formatted according to -[contiki/doc/code-style.c](https://github.com/contiki-os/contiki/blob/master/doc/code-style.c). - -The Contiki source tree contains scripts to assist with correct code formatting -and we recommend [Uncrustify](http://uncrustify.sourceforge.net/) as the -preferred auto formatter. Everything is under -[tools/code-style](https://github.com/contiki-os/contiki/tree/master/tools/code-style). - -If you wish, you can format all changed resources in your working tree -automatically if the -[tools/code-style/uncrustify-changed.sh](https://github.com/contiki-os/contiki/blob/master/tools/code-style/uncrustify-changed.sh) -script is added as a [Git pre-commit -hook](http://git-scm.com/book/en/Customizing-Git-Git-Hooks) to your Git -configuration. - -Here are some examples of what you can do: -* To check a file's style without changing the file on disk, you can run this: -`./tools/code-style/uncrustify-check-style.sh ` -This script will only accept a single file as its argument. - -* To auto format a file (and change it on disk) you can run this: -`./tools/code-style/uncrustify-fix-style.sh ` - -* `uncrustify-fix-style.sh` will accept a space-delimited list of files as its argument. Thus, you can auto-format an entire directory by running something like this: -``./tools/code-style/uncrustify-fix-style.sh `find cpu/cc2538 -type f -name "*.[ch]"` `` - -This is _not_ a silver bullet and developer intervention is still required. Below are some examples of code which will get misformatted by uncrustify: -* Math symbol following a cast to a typedef -``` - a = (uint8_t) ~P0_1; /* Cast to a typedef. Space gets added here (incorrect) */ - a = (int)~P0_1; /* Cast to a known type. Space gets removed (correct) */ - a = (uint8_t)P0_1; /* Variable directly after the cast. Space gets removed (correct) */ -``` - -* `while();` will become `while() ;` (space incorrectly added after closing paren) - -* `asm("wfi");` becomes `asm ("wfi");`: A space gets added before the opening paren, because the `asm` keyword stops this from getting interpreted as a normal function call / macro invocation. This is only a problem with `asm`. For instance, `foo("bar");` gets formatted correctly. - -Naming ------- - -We require that all code contributed to the Contiki tree follow the -Contiki source code naming standard: - -* File names are composed of lower-case characters and dashes. Like - this: simple-udp.c -* Variable and function names are composed of lower-case characters - and underscores. Like this: simple_udp_send(); -* Variable and function names that are visible outside of their module - must begin with the name of the module. Like this: - simple_udp_send(), which is in the simple-udp module, declared in - simple-udp.h, and implemented in simple-udp.c. -* C macros are composed of upper-case characters and underscores. Like - this: PROCESS_THREAD(). -* Configuration definitions begin with the module name and CONF_. Like - this: PROCESS_CONF_NUMEVENTS. - -How to Contribute Code ----------------------- - -When your code is formatted according to the Contiki code style and -follows the Contiki naming standard, it is time to send it to the -Contiki maintainers to look at! - -All code contributions to Contiki are submitted as [Github pull -requests](https://help.github.com/articles/using-pull-requests). Pull -requests will be reviewed and accepted according to the guidelines -found in the next section. - -The basic guidelines to to start a Pull-Request: -* Create a new branch for your modifications. This branch should be based on the latest contiki master branch. -* If you already added the commits to another branch you can [cherry-pick](http://git-scm.com/docs/git-cherry-pick) them onto your new branch. -* Push the new branch to github. -* Raise the new Pull Requests on this new branch. Raising a Pull Request for the master branch is almost always a bad idea. -* If changes are requested do not close the pull request but rewrite your history. [Details about rewriting your history](http://git-scm.com/book/en/Git-Tools-Rewriting-History) -* You now force-push the changes to github. The pull-request is automatically updated. - -In Git terminology this is equivalent to: -* Make sure you have the original contiki repo as origin. -```bash -$ git remote -v -contiki-orig https://github.com/contiki-os/contiki.git -``` -* If not add it -```bash -$ git remote add contiki-orig https://github.com/contiki-os/contiki.git -``` -* Make sure you have the latest version of your remotes -```bash -$ git remote update -``` -* Create a new branch "my_new_feature" based on the latest contiki master branch -```bash -$ git checkout contiki-orig/master -b my_new_feature -``` -* Add your work. For example by cherry-picking your changes from another branch. -```bash -$ git cherry-pick -``` -* Push to _your_ github repository -```bash -$ git push origin my_new_feature -``` -* Make a Pull Request for that branch -* Rewrite your history if requested -```bash -$ git rebase -i contiki-orig/master -``` -* As rewriting your history can break things you must force-push the changes. **Warning**: Force-pushing normally is dangerous and you might break things. Make sure you are never force-pushing branches other people are supposed to work with. -```bash -$ git push origin my_new_feature -f -``` -* NOTE: To avoid all the pain of selectively picking commits, rebasing and force-pushing - begin your development with a branch OTHER THAN your master branch, and push changes to that branch after any local commits. - -Pull Request Merging Policy ---------------------------- - -Pull requests (PRs) are reviewed by the [merge team](https://github.com/orgs/contiki-os/people). -Generally, PRs require two "+1" before they can be merged by someone on the merge team. -The since Contiki 3.0, the merging policy is the following: -* The PR receives **one "-1"** from a merge team member (along with specific feedback). The PR is closed. A "-1" must be accompanied with a clear explanation why the PR will not be considered for inclusion. -* The PR receives **two "+1"** from merge team members. The PR is merged. -* The PR was inactive for **two months**. A team member may either: - * Comment "Is there any interest for this PR? Is there any work pending on it? If not I will close it in **one month**." Back to initial state in case of activity, close otherwise. - * Comment "I approve this PR. If nobody disapproves within **one month**, I will merge it." Back to initial state in case of activity, merge otherwise. - -There is an exception to the rule. -Code that requires esoteric expertise such as some applications, platforms or tools can be merged after a single "+1" from its domain expert. - -Travis / Regression testing ---------------------------- - -[Travis](https://travis-ci.org/) is a service that runs regression -tests. If you make a pull-request for Contiki this is automatically -forwarded to Travis and regression tests are run. A box with -information about the state of you pull request should show up after a -minute or two. - -If the test fails it is likely that something is wrong with your -code. Please look carefully at the log. It might also be that some -package on the testing VM was updated and causes the build to fail. If -you are sure that is is not your code causing the tests to fail start -a new issue describing the problem. Also note this in your pull -request. - -You can also register at [Travis](https://travis-ci.org/) for -free. Once you activated your Contiki repository, every push will be -tested at Travis. The configuration is part of the contiki repository -and testing will therefore work out-of-the-box. At Travis you then get -an overview of the state of each of your branches. - -New Platforms -------------- -A new hardware port will be considered for inclusion in mainline Contiki -if it satisfies the following rules: - -* There must be at least one person willing and committed to maintain it. -They may but do not have to be the people who wrote the code. Similarly, -they may but do not have to be affiliated with the hardware manufacturer. -In the first instance, code maintenance would mean keeping the port up to -speed by submitting pull requests as Contiki moves forward. In the longer -term, people who maintain a reasonable level of commitment and who demonstrate -that they know what they're doing may be invited to become repo collaborators. -* The hardware must be commercially available and of interest to a wide audience. -In other words, ports for bespoke hardware built for e.g. a specific project / -a single customer / niche markets are more suitable for a Contiki fork. -* The code must strictly adhere to the Contiki code style, as discussed above. -* The new files must have a clear copyright notice and license header. Contiki's -preferred software license is the -[3-clause BSD](http://opensource.org/licenses/BSD-3-Clause). -Other licenses may also be considered -as long as they are compatible with the 3-clause BSD (e.g. the Apache 2.0 license). -Conversely, code distributed under GPL cannot be considered. The same applies to -bespoke licenses, such as those allowing use or redistribution only together with -certain kinds of hardware. -* The port must demonstrate a certain degree of completeness and maturity. Common sense -applies here. -* The port must be accompanied by examples demonstrating basic functionality. This could -be a set of examples under `examples/` and/or documentation of -which existing examples are meant to work. -* The port must provide compile regression tests by extending the existing travis -integration testing framework. Again, we can't specify explicitly -what those tests should be, but something more interesting than hello-world is expected. -* The work must be documented. The documentation could be README.md files -under the platform / cpu / example dirs or wiki pages. Doxygen comments are -also encouraged. The documentation should include: - * A getting started guide, including a list of tools required to use the platform -(e.g. toolchain, software to program the device), where to get them from and brief notes -how to install them (can simply be a list of links to external guides) - * A list of things which will work off the shelf - * A list of things which are not meant to work, if any - * Additional reading resources (e.g. datasheets, hardware user guides, web resources) - * A ToDo list, if applicable. -* It must be possible to use the port using free software. We do not discourage the -use of commercial software (e.g. support for a commercial toolchain), quite the opposite. -However, we will insist on the existence of a free alternative for everything. - -After the port has been accepted, things meant to work off the shelf should -keep working off the shelf as Contiki moves forward. - -We appreciate that, for many people, contributing to Contiki is a spare time -activity and our expectations from port maintainers take this into -consideration. All we ask from maintainers is to comment on and address -relevant pull requests at a reasonable frequency and to make sure travis keeps -passing. In other words, we just want platforms to stay healthy over time and -to thus avoid becoming very broken / obsolete. +For contribution guidelines, see [doc:contributing]. +[doc:contributing]: https://github.com/contiki-ng/contiki-ng/wiki/Contributing