Code Contribution Guidlines

created by hek , updated by petewill

Contributing Code

The MySensors project is open and welcomes new code contributors. If you plan to make a large refactoring or massive changes, please create an issue first to allow us to give feedback. We wouldn't want you to spend alot of time on something that wouldn't make it into the project.

Fetching the MySensors repository from GitHub

The normal workflow is that you create a fork of the MySensors repository by visiting https://github.com/mysensors/MySensors . Press the "Fork" button found here:

Now it's time to download the forked repository to your computer.

We recommend installing the git command line tool. It's available for all types of platforms.

To fetch the repository from github, run the following command in your terminal window:

# Clone the repository to your computer.
> git clone https://github.com/<your username>/MySensors.git

# Change directory to your newly cloned repository
> cd MySensors

# Check out development branch
MySensors> git checkout development

Make sure to change above. Now you probably want to setup your local repository to allow fetching from a remote upstream (that is the main MySensors repository) too keep things up-to-date. This only needs to be done once.

MySensors> git remote add upstream https://github.com/mysensors/MySensors.git

Now you are ready to use your favourite editor or IDE to make the patch and/or enhancement. Fix all warnings when building (the PR won't be accepted otherwise). When finished, make a habit of fetching the latest changes from upstream before committing.

# Fetch upstream changes
MySensors> git fetch upstream
# Merges upstream changes into your local branch
MySensors> git merge upstream/development

# Stage file(s) to for commit to your local repository. Repeat the add command for each changed file or folder you want to commit.
MySensors> git add <file or directory>
# Limit commmit message subject to 50 characters. See "keep a tidy git log" below.
MySensors> git commit -m "Your commmit message"
# Push changes to yor github repository
MySensors> git push

Not you are ready to create a pull request on github.com. Go to your cloned repository and press "New Pull Request":

Enter your description for the pull request and create it.

Our build server will run tests on the pull requests. It will check the following before accepting it.

  1. Validity of commit message. Keep subject below 50 chars. Body below 70 chars.
  2. Codestyle. See "Coding Guidelines" below.
  3. No build errors or warnings. We run a series of test builds for different platforms (AVR, ESP8266, SAMD, Linux/RPI). Save yourself a lot of troubles by eliminating warnings before pushing PR.
  4. Signed Contributor License Agreement (CLA). You can sign it here.

Note! We only accept pull requests on the development branch. Master is only used for releases.

Commit Messages - Keep a tidy git log

We'd like to keep the commit log readable, relevant and tidy. We highly recommend you to read this article on the subject.

You can find the current MySenosrs development git log here to get an idea of what a good commit message should look like:

Amending Git Messages or PRs

If your PR gets rejected or if you want to make additions. Amending is the way to go. Followed by a force push. Github will update the PR automatically and our build server will try again.

Rebasing an out-of-date PR

enter image description here

If changes are introduced to the development branch that conflicts with an open PR, the PR might not be possible to merge. You will have to resolve the conflicts and update the PR.

# Fetch upstream changes
MySensors> git fetch upstream
# Merges upstream changes into your local branch
MySensors> git checkout development
MySensors> git merge upstream/development

# Rebase the branch you filed the PR from against your updated development branch
MySensors> git checkout <yourbranch>
MySensors> git rebase development
# You can expect merge conflicts to occur here, which you will need to resolve, add and commit.
# ...
# Force push your updated branch so the PR gets updated
MySensors> git push HEAD:<yourbranch> -f

Signing CLA

To accept contributions to the MySensors core library, you have to sign our contributor license agreement found here: https://www.clahub.com/agreements/mysensors/MySensors

This is not needed, if you just want to add a new example in the examples repository: https://github.com/mysensors/MySensorsArduinoExamples

Coding Guidelines (core library)

Artistic style can be used to verify coding standard and the repository holds a rules definition file at '.astylerc' which can be used to get the rules below verified by the tool. We also offer a git-commit hook to verify the coding structure of the commit in question. It can be installed using 'hooks/install-hooks.sh' and works on Linux, MacOS and Windows (cygwin/bash based shells).

  • We use camelCase for function and variable names.
  • Tab-character for white space/indentation.
  • All control statements ('if', 'for', 'while' etc.) should include curly braces {}. Even one-liners.
  • Curly braces should follow "One True Brace Style" format like this:

    void myFunction()
    {
      int i;
      for (i = 0; i < 42; i++) {
          if (0 == i) {
              continue;
          }
      }
    }
  • All new code should include documentation in doxygen. See an example here.

  • Avoid using Systems Hungarian notation:
    bool bDone;
    int iCnt;
  • All lines should be kept at 100 character width or less
    • When breaking logical conditionals, keep the conditionals on the first line like this:
      if (thisVariable1 == thatVariable1 ||
          thisVariable2 == thatVariable2 ||
          thisVariable3 == thatVariable3)
  • Preprocessor blocks should be indented:
    #ifdef _WIN32
      #include <windows.h>
      #ifndef NO_EXPORT
          #define EXPORT
      #endif
    #endif
  • Preprocessor definitions should be indented if linebroken:
    #define Is_Bar(arg,a,b) \
      (Is_Foo((arg), (a)) \
       || Is_Foo((arg), (b)))
  • Preprocessor conditions should NOT be indented to source level, but be kept in first column:
    #ifdef UNICODE
          text = wideBuff;
    #else
          text = buff;
    #endif
  • C++ comments should be indented to source level, and not be kept in first column:
    void Foo()
    {
      // comment
      if (isFoo) {
          bar();
      }
    }
  • Source files should be stored in UTF-8 encoding with LF/"Unix" style line endings

Comments