Merge pull request #125 from contiki-ng/simonduq-patch-2
CONTRIBUTING.md: link to wiki where the content has moved
This commit is contained in:
commit
1dfa99c0e8
279
CONTRIBUTING.md
279
CONTRIBUTING.md
|
@ -1,278 +1,3 @@
|
||||||
Code Contributions
|
For contribution guidelines, see [doc:contributing].
|
||||||
==================
|
|
||||||
|
|
||||||
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 <path-to-file>`
|
|
||||||
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 <path-to-file>`
|
|
||||||
|
|
||||||
* `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(<condition>);` will become `while(<condition>) ;` (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 <HASH OF COMMIT>
|
|
||||||
```
|
|
||||||
* 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/<new-hardware-port>` 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.
|
|
||||||
|
|
||||||
|
[doc:contributing]: https://github.com/contiki-ng/contiki-ng/wiki/Contributing
|
||||||
|
|
Loading…
Reference in New Issue