Skip to content
This repository has been archived by the owner on Jun 27, 2019. It is now read-only.

Contributing

Jump to bottom
Gustavo Lima Chaves edited this page Dec 17, 2015 · 35 revisions

Before you contribute

We don't ask any kind of copyright assignment, you own the copyright of your changes. However we need to ensure you're the author of your changes and please do so by following http://developercertificate.org/

When submitting code to this project, please indicate that you certify you are able to contribute the code by adding a signed-off-by line at the end of your commit message (using your real name) such as:

Signed-off-by: Random J Developer <[email protected]>

Contributions flow

To make contributions to Soletta you should:

  1. Fork the repository.
  2. Make commits in series as short as possible - avoid adding a lot of unrelated patches in the same pull request.
  3. Make a pull request for the selected branch. The pull request's subject should be short and descriptive, issues linked to it should be in its request message, not in the commit messages.
  4. Wait a few days for reviews - if after a couple days you don't see any comments, please poke us by email / IRC. It shouldn't happen.
  5. You need at least one of the core developers to agree that your code is good to be merged (+1), but depending on the pull request's complexity, wait for more than one acknowledgment.
  6. If no changes to your proposed code are required, the pull request will be rebased on top of the master branch, pushed and closed by one of the core developers.
  7. If changes are required:
  • Make a new pull request with an updated version on its subject, e.g "Add GPIO support for RIOT [v2]"
  • Link the previous pull request to this one (by GitHub's citation markup), so people can see previous discussions
  • Add a changelog between pull request versions in the pull request messages
  • Close previous pull requests when uploading new ones, to avoid people commenting in outdated work
  • Go back to step 4

Commits

Commits should be split by fix or featured added. Following that rule, try to keep commit series as granular as possible, so if some of them are wrong they can be dropped and the others will be applied. Also it makes it easier to find eventual regressions later. Code review is much easier in this case as well.

Avoid coding styles changes in the same commits of real changes. Also only send coding style change commits if it seems really necessary -- we control code style quality by helper tools.

Please invest some time on writing useful commit messages. The following template should be used

component: short description

more details paragraph 1

more details paragraph 2

Signed-off-by: Random J Developer <[email protected]>

Example:

common: add macro for static checking array size

In C there's a feature to improve the check of the array size being
passed to a function, by specifying 'static' before the array
size. However this feature is not supported on C++.

This patch wraps the usage into a macro to let the public headers to be
used in C++ programs.

Signed-off-by: Caio Marcelo de Oliveira Filho <[email protected]>

If it's a bug fix, please add enough information to make it possible to be reproduced.

Logs or backtraces are welcome.

For memory issues, a valgrind log could be pasted as well.

Coding Style

We follow a style defined in a uncrustify schema. It's all specified in there, but the summary is similar to Linux's style, but using 4 spaces and no tabs. One should check the style of commits or staging area changes by using our tools/check-style.py. See GIT Hooks below.

License

Files should contain a license header and there specify who owns the copyright. Since Soletta is to be used in small operating systems and these often are compiled as a single statically linked binary we require the BSD-3 clause license.

Whenever adding new files, ensure the license is included at the top of the file. One can check the license using our tools/check-license.sh. See GIT Hooks below.

Exceptions are always painful to manage, but if there is an exception to your contribution please let us know and we can discuss about it. Eventually we can accept it in the main repository or create another repository with modules using different licenses, in this case we need to add entry-points so they are used (many are already supported, such as the flow and linux-micro modules).

Significant changes should also list their author in AUTHORS.

Test and Validate

Before sending patches please run our tests:

    make check
    make check-fbp
    make check-fbp-bin

If you did changes in C, please check your memory using Valgrind (to catch memory errors such as leaks and invalid access) and the overall coverage of your tests:

    make check-fbp-valgrind
    make coverage

GIT Hooks

We recommend contributors set a pre-commit GIT hook to check before sending patches:

#!/bin/sh
./tools/check-style.py || exit 1
./tools/check-license.sh || exit 1
exit 0

Save this as .git/hooks/pre-commit and remember to make it executable (chmod +x .git/hooks/pre-commit).

Notice that check-style.py requires uncrustify 0.60, check this page for more info on how to install this specific version.

Clone this wiki locally