contiki/CONTRIBUTING.md

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 <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.