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.
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.
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:
- URL for your fork:
More info on Gitlab official docs:
Clone your fork in your local computer
Clone your fork in your local computer
git clone https://gitlab.com/YOUR_USERNAME/rhomb.iot
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:
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)
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.
- 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:
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.
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:
- The user should have both remote servers in his local machine
- The fork (his fork) is called
origin, while main remote is called
- 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 email@example.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.
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.