Merge pull request #746 from sieben/contributing
Adding a CONTRIBUTING.md file to use a nice github feature
This commit is contained in:
George Oikonomou
commit
7d0284ed18
263
CONTRIBUTING.md
Normal file
263
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,263 @@
|
|||
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 [[Pull Request Policy]]
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in a new issue