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
In this guide you will find the procedure for working with our Git repository.
- Install/Configure Git
- Fork the rhomb.IoT repository
- Clone your fork in your local computer
- Enable Git Flow in your local
- In your local, add a new feature branch using Git Flow
- Make commits in your new feature
- Push the feature to your remote repository on Gitlab
- Make a Merge Request on Gitlab to push your your changes
It may seem like a lot of steps, but the truth is that you soon get used to it, and in the end everything happens without you having to think much about how to do it.
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.
Fork the rhomb.IoT repository
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, please, see this for more details:
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:
Any changes you made in your fork can be later sent to the original repo using the "Merge Request" option of Gitlab. An administrator will inspect your changes and accept it or propose a change.
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.
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.