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 Feb 25, 2016 · 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

    1. When the PR is good to be integrated, there are two possibilities:
    2. the author is a Soletta commiter
    3. the author does not have Soletta commit rights

    If you're in case 2, just wait until a commiter integrates your patch. If you're in case 1 and will merge a PR, you may never, ever, hit Github's merge button to achieve that. Instead, rebase the PR onto current master branch, then push the changes directly to the master branch (via command line). The master branch is so that it only accepts fast-forwards, so it will complain if you did not rebase the PR before. The commands for commiter to integrate a PR will then be as follows:

    git checkout reviewed_branch
git fetch origin
git rebase origin/master
git push origin HEAD:master
    1. Close the PR after it was integrated and pushed, commenting it was done in the PR's web page. Alternatively you may use "Closes gh-" in the top commit's message, so that Github will automatically close the PR when it lands upstream.

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.

Updates on submodules

Soletta's submodules, whenever need to be moved forward (or changed anyhow) from the point they were at a given time, have to have that signaled to downstream users by means of a special flow. Moving them forward can be achieved with following command, for example:

git submodule update --remote

After the desired changes in the submodule in question, git diff should be showing you something like:

diff --git a/src/thirdparty/tinycbor b/src/thirdparty/tinycbor
index f0791a2..b80318a 160000
--- a/src/thirdparty/tinycbor
+++ b/src/thirdparty/tinycbor
@@ -1 +1 @@
-Subproject commit f0791a2a12599c82e9b65f2923eb1cdd6c141e5d
+Subproject commit b80318ab0640efa98147836380c7937a59dc327d

Get those changes in a commit and submit them.

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, specifying who owns the copyright. Since Soletta is to be used in small operating systems (besides Linux) 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 licensing status of new files from commits 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 those cases 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 (if you add any sample Soletta application in the patches, the last rule will exercise that):

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

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

    make check-fbp-valgrind
    make coverage

By taking these steps, you're most likely to get the CI tool's approval or your pull request. Without the bot being green, it's impossible anyone will accept your patch.

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