.. include:: /keyword.rst


======================
How to Contribute
======================

.. contents:: Sections
    :local:
    :depth: 2

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` (|GITLAB|). Changes to the source code
must be submitted using `gitlab's merge requests <https://docs.gitlab.com/ee/user/project/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 <https://git-scm.com/doc>`_ 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
<https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html>`_
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:

.. prompt:: bash $

	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:

.. prompt:: bash $ auto

	$ 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
(|GITLAB|).


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

.. prompt:: bash $ auto

	$ 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:

.. prompt:: bash $

	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:

.. prompt:: bash $

	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:

.. parsed-literal::

	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:

.. prompt:: bash $

	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.

.. prompt:: bash $ auto

	$ 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:

.. prompt:: bash $

	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.