Skip to content

Contents

Contributtion Guidelines

We're really glad you got here ❤

Before start to contribute, you’ll want to be familiar with rhomb.io, as a hardware project, and rhomb.IoT, as a firmware project. Know how to configure and use a device as explained on the user documentation is the basic.

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

Is a good idea start an issue before send 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). Is a good idea to enable the option to execute format code before save.

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.

An overview:

  1. Install/Configure Git
  2. Fork the rhomb.IoT repository
  3. Clone your fork in your local computer
  4. Enable Git Flow in your local
  5. In your local, add a new feature branch using Git Flow
  6. Make commits in your new feature
  7. Push the feature to your remote repository on Gitlab
  8. 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.

Configure 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.

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 continue. When you are inside the repository there is the button Fork on the top right side, please, see this for more details:

Creating a fork on Gitlab

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/rhomb.iot

URL for your fork:

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

Any change you made in your fork can be later send 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 en 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 clone 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 whith 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 continue.

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

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 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 other team member and he/she needs 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 accept your code will be part of the original repository. If there is any problem or mistake you will get a notice from a team member to apply the required changes. On this case you will need to do new commits in your local repo and do again the merge request process.

Conclussion

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