Code Contributions

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.

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.

The Contiki source tree contains tools to assist with correct code formatting. We provide configuration files and helper scripts for two tools: GNU Indent and Uncrustify. Everything is under tools/code-style.

These tools can format all changed resources in your working tree automatically if the tools/code-style/uncrustify-changed.sh script is added as a Git pre-commit hook to your Git configuration.

GNU Indent

The tree provides a configuration file, tools/code-style/indent.pro along with a small script to make it easier to use, tools/code-style/contiki-indent. Note that while the output from this tool is pretty good, manual formatting might also be needed.

Uncrustify

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. Pull requests will be reviewed and accepted according to the guidelines found in the Pull Request Policy

Advice for Contributors

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.

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. Ports of customized hardware platforms are typically unsuitable for inclusion in either of these repositories, but individual components of the port, such as a device driver, may be of interest.