How to Contribute

This document explains the contribution process of IoT Yocto. Please read carefully and entirely this document before submitting any changes.

IoT Yocto source code is hosted on GitLab (http://www.gitlab.com/mediatek/aiot). Changes to the source code must be submitted using gitlab’s merge requests. The following sections will describe how to create changes, how to push these changes for review as merge requests, and how to update these Merge Requests until the change is accepted and merged.

Note

This document show the usage of a few git commands, but this document does not intend to teach you git. If you are not familiar with git, it is recommended to look at the git documentation as well.

Note

Examples in this document are done using the John Doe user on the meta-rity project. Please adapt your commands to your name and project.

Creating a fork

IoT Yocto projects use a fork-based model for contributions. In order to open a Merge Request, you should first fork the project you want to contribute to.

To fork a project, please go to the project’s home page, in the top right, click on the Fork button. You can fork the project on your own personal namespace or any other namespace, where, you have at least Developer role.

Cloning locally the code

To contribute to a IoT Yocto project, you first need to retrieve a local copy of the source code. To do so, clone the upstream project (not the fork you just created). For example, let’s use meta-rity project:

git clone git@gitlab.com:mediatek/aiot/rity/meta-rity.git

You now have the source code of the project you want to contribute to. You can inspect the configured remote on this project by issuing the following command:

git remote -v
rity    ssh://git@gitlab.com/mediatek/aiot/rity/meta-rity.git (fetch)
rity    ssh://git@gitlab.com/mediatek/aiot/rity/meta-rity.git (push)

You should have only one configured remote, that points to the upstream project (http://www.gitlab.com/mediatek/aiot).

You should now add your fork as a new remote with the following command:

git remote add fork git@gitlab.com:jdoe/meta-rity.git
git remote -v
fork    git@gitlab.com:jdoe/meta-rity.git (fetch)
fork    git@gitlab.com:jdoe/meta-rity.git (push)
rity    ssh://git@gitlab.com/mediatek/aiot/rity/meta-rity.git (fetch)
rity    ssh://git@gitlab.com/mediatek/aiot/rity/meta-rity.git (push)

Creating a branch with your changes

Before starting to make changes, it is recommended to create a new branch where you will apply your changes. By convention branches should be prefixed with your user name. This makes it easier to know which branch is owned by whom.

For example you could use the prefix jdoe/. If you are working on some clean-ups you could for example name your branch: jdoe/clean-ups.

To create your branch you can run the following command:

git checkout -b jdoe/clean-ups

Note

IoT Yocto projects manage several branches, and you should create your development branch based on the desired target branch.

Committing your modifications in new commits

After making the modifications you want, you should commit the changes. The best practice is to make one commit per change or per type of change. For example if you planned to make the following changes: remove some extra white space, add a new feature, and fix a typo; these should ideally be 3 different commits.

Once you have a change ready, you can commit it using the following commands:

touch newfile.txt
git add newfile.txt
git commit -s

The last command will open your text editor and prompt you to write a commit message. Correctly formatting commit message is very important. You can find a very good guide here <https://cbea.ms/git-commit/>_. Basically your commit should look like this:

one-line short commit description

Long commit description that can
be over several
lines.

Signed-of-by: John Doe <jdoe@company.com>

You are also encouraged to look at previous commits to keep consistency.

Once you have committed all your changes you can inspect them using git log. In case you made mistakes or need to change a commit you add use git rebase -i or git commit --amend. Please check the git documentation on their usage.

Sending a Merge Request (MR)

Pushing the code

When you are happy with your commits you can submit them for merging using a Merge Request (MR). To do that you can push your branch on your fork.

Before pushing your branch, make sure it is up-to-date with the upstream target branch. For example, if you want to merge your branch into the kirkstone branch on the upstream project you should run:

git pull --ff-only rity kirkstone

When pushing your branch on the GitLab server, GitLab will return a URL that will easily allow you to create a Merge Request for the branch you just pushed.

git push fork jdoe/clean-ups
Enumerating objects: 12, done.
Counting objects: 100% (12/12), done.
Delta compression using up to 8 threads
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 1.80 KiB | 1.80 MiB/s, done.
Total 7 (delta 4), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for jdoe/clean-ups, visit:
remote:   https://gitlab.com/jdoe/meta-rity/-/merge_requests/new?merge_request%5Bsource_branch%5D=jdoe%2Fclean-ups
remote:
To gitlab.com:jdoe/meta-rity.git
 * [new branch]                jdoe/clean-ups-> jdoe/clean-ups

Visiting the link sent by the remote will allow you to create a Merge Request. You will see a form asking you for some information about your Merge Request.

Filling the title and description

By default the title and description of the Merge Request will be pre-filled with the commit description of the first commit of your branch. If your branch has more than one commit it is often useful to rewrite the Merge Request title and description to better describe the content of all the commits. It is also often useful to add some other information like how it was tested and with which command. This will give the reviewer the ability to try the changes herself or himself.

Setting the target branch

Sometimes you don’t want to push your changes in the default branch, in that case you need to make sure you are submitting the Merge Requests against the branch you based your commits on.

You can change the target branch by clicking on the Change branches link.

Setting the Assignee fields

Merge Request will automatically be assigned to the corresponding maintainer.

The Draft status

Sometimes, your work is Work In Progress and you just want to have some feedback from maintainer. To avoid the maintainer to merge your work, you should click on the Mark as draft button. This will prefix your title Merge Request with “Draft:” and maintainer will not merge it. Once it is ready, don’t forget to mark it as ready.

Submit the Merge Request

Once you filled all the fields described above, you can click on the Create a merge request button.

Review of your Merge Request

The maintainer of the component you modified will review your Merge Request. When you get some feedback asking you to make some changes, you will need to modify your commits using git rebase -i or git commit --amend. Please do not close the ongoing Merge Request to open a new one. Instead, you should force push your branch:

git push -f fork jdoe/clean-ups

Force pushing your branch allows to keep track of all the comments on the MR. Moreover, even when force pushing, GitLab keeps track of the different versions of the MR. These versions are only accessible inside the MR and will not appear on the git history once merged.

When your Merge Request is deemed good enough for merging, the maintainer will click on the “Approve” button and merge the branch.