Skip to content

Contribution Guidelines

We're really glad you got here ❤

Before starting to contribute, you’ll want to be familiar with rhomb.io as a hardware project, and Rhomb.IoT as a firmware project. Knowing how to configure and using a device as explained on the user documentation is a must.

We use Git with Gitlab and organize the repository with the methodology of Git Flow. The process, which includes forking, branching, managing issues and sending merge requests are explained further below.

It is a good idea starting an issue before sending a contribution, so you can discuss the changes in advance with the team.

Coding Style

Use Google C++ Coding Style. With VS Code and other editors you can use the option Format Code to make your life easier. The repository contains a settings file with format code configuration for VS Code (.vscode/settings.json). It is a good idea to enable the option to execute format code before saving.

Install the recommended extensions listed on .vscode/extensions.json. For example with Editorconfig we keep consistency with tabs and trailing spaces and with Todo Tree we can find pending todos or bugfixes in the code.

Working with Git

There is no special configuration for git. If it is your first time with it you'll need a little patience to get started, once you know the steps everything will be simple.

On this article we won't explain how to use Git from the beginning; there are many guides on the Internet for this. We can recommend the one they've made in Gitlab: Start using Git on the command line.

Forking Rhomb.IoT

A fork is a copy of an original repository that you put in another namespace where you can experiment and apply changes that you can later decide whether or not to share, without affecting the original project.

Our repository is in Gitlab, you'll need an account before continuing. When you are inside the repository there is the button Fork on the top right side:

In the end you will find that the Rhomb.IoT repository has been copied into your personal account. You'll be able to tell the difference because each one has a different URL

  • URL original repo: https://gitlab.com/rhombio/things360/rhomb.iot
  • URL for your fork: https://gitlab.com/YOUR_USERNAME/rhomb.iot

More info on Gitlab official docs:

Creating a fork on Gitlab

Clone your fork in your local computer

Clone your fork in your local computer

git clone https://gitlab.com/YOUR_USERNAME/rhomb.iot

Note

After clone, you should follow the steps on the user guide to setup your development environment with PlatformIO.

Enable Git Flow

Git Flow is a methodology to work with Git. You can find and explanation here:

Gitflow Workflow

If you have cloned your fork, open a console, move to your local repository and execute the command:

git flow init

It will ask you some values for naming your git branches:

  • Production branch: master
  • Development Branch: develop

Keep all the other branches with the default name (feature, fixes, releases... etc)

Warning

After git flow init your local repository will be in the develop branch. You should know the difference between master and develop branches on a git repository. You should never make a change in the master branch.

Add a feature branch

The common way to add or change something in the code is creating a feature branch.

To create a feature run this command:

git flow feature start my-feature

Our feature has a name, my-feature, Keep it short and descriptive with lower case always.

Make commits in your feature

When your feature has been created you can start coding. Every change in the code should be saved on the repo whit a commit.

Some tips:

  • Whenever possible, work on a feature branch
  • A feature must contain changes to fix or change only 1 thing. We don't mix different problems in the same feature (unless they are related)
  • Make small commits. This helps the team to better analyze the code.
  • Be descriptive in your commits in no more than 50 characters

Please, read the article of Chris Beams about how to write good commits:

How to Write a Git Commit Message

Push the feature to your remote fork

The first step to publish your changes in the main repository is to publish them first in your fork.

Execute:

git status

Should output something like this:

On branch feature/my-feature
nothing to commit, working tree clean

If your repo has pending changes (you don't see working tree clean) commit them before continuing.

Continue publishing your changes:

git push origin feature/my-feature

Now your fork is available in your remote repository. Open your browser and check your Gitlab account.

Do a Merge Request

It is time to send your changes to the original repository. For that purpose we need to do a Merge Request on Gitlab. There is a button on the left sidebar of Gitlab for this, the process is well explained in the Gitlab Docs: How to create a merge request

Basically when you create a merge request you need to select the source branch, the feature/my-feature in your fork, and a destination branch, a new one or existing in the original repository.

You should fill all the information of the Merge Request form. Please explain in your request all the changes you have done and why. Your merge request will be checked by another team member and they need your info to return a good feedback. This is just a simple procedure where a second person checks that the changes are correct and the code works well. Coding errors are imminent and four eyes will see better than two.

After your Merge Request is accepted your code will be part of the original repository. If there is any problem or mistake you will get a notification from a team member to apply the required changes. In this case you will need to do new commits in your local repo and do again the merge request process.

Update local with main remote

Throughout the development lifecycle, the main Rhomb.IoT repository will receive changes from other users that you must import into your local repository (your computer) and your remote fork (your Gitlab account).

This image illustrates what the development lifecycle would look like with git:

Git Development Lifecycle

  • The user should have both remote servers in his local machine
  • The fork (his fork) is called origin, while main remote is called upstream
  • User should add upstream to his list of remote servers (using command git remote add upstream ...)
  • User can make push and pull request from his fork, he is the owner, but from main remote, upstream, he only can call pull or fetch
  • User can add code to main repository using a merge request from remote fork (Gitlab)

How to update from main remote

First, add main remote to your local repo:

git remote add upstream git@gitlab.com:rhombio/things360/rhomb.iot.git

Be sure your local repo is clean and working on develop:

$ git status
On branch develop
Your branch is up to date with 'origin/develop'.

nothing to commit, working tree clean

Refresh your local branch with upstream

git fetch upstream

And apply any new change:

git pull upstream develop

Now your local repo is up to date with main repo. You can update your remote fork to be also up to date with main:

git push origin develop

Now both remote servers and your local copy are using the same code version.

Conclusion

We love Open Source. We use it everyday for our daily work and we want to do our best to give back to the community what it has given us. We really appreciate your participation. At Rhomb.IoT you will find a team of people who are much more than good professionals, they are good people.

Don't be afraid to ask for the help you need.

Comments