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.
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
documentation as well.
Examples in this document are done using the John Doe user on the
meta-rity project. Please adapt your commands to your name and
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.
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
git clone firstname.lastname@example.org: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://email@example.com/mediatek/aiot/rity/meta-rity.git (fetch) rity ssh://firstname.lastname@example.org/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 email@example.com:jdoe/meta-rity.git git remote -v fork firstname.lastname@example.org:jdoe/meta-rity.git (fetch) fork email@example.com:jdoe/meta-rity.git (push) rity ssh://firstname.lastname@example.org/mediatek/aiot/rity/meta-rity.git (fetch) rity ssh://email@example.com/mediatek/aiot/rity/meta-rity.git (push)
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:
To create your branch you can run the following command:
git checkout -b jdoe/clean-ups
IoT Yocto projects manage several branches, and you should create your development branch based on the desired target branch.
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 <firstname.lastname@example.org>
You are also encouraged to look at previous commits to keep consistency.
Once you have committed all your changes you can inspect them using
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.
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
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.
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.
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.
Merge Request will automatically be assigned to the corresponding maintainer.
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.
Once you filled all the fields described above, you can click on the Create a merge request button.
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.