MISC-TN-028: GitLab-based workflow

Info Box

History

Version	Notes
August 2023	First public release

Introduction

DAVE Embedded Systems uses GitLab as the primary source code management platform. This Technical Note describes the typical GitLab-based workflow we use and that our partners are strongly encouraged to adopt as well.

Essential steps of the workflow

This section describes in detail the essential steps the workflow is composed of. To this end, we will use a very simple example based on an ad hoc repository, named test0. The goal is to write the first release of the code by following the recommended workflow.

Once the repository is created on GitLab, we create an issue. Every implementation should start with this step: first of all, create an issue!

In this case, we call the issue "First release" as shown by the following picture:

Then, we create a merge request associated with the issue. We instruct GitLab to automatically create a branch associated with this issue as well. The branch will be called 1-first-release and its source branch is master. This means then when the merge request is accepted, the new code in the branch 1-first-release will be merged into the branch master.

Please note that the merge options are so that the branch will be deleted when the merge request is accepted. This usually makes sense because we don't need to keep the branch when the job is done. If you are asking to yourself, don't worry: although the branch is deleted, commits will not be lost. Therefore, the history of changes will be preserved.

On GitLab side everything is in place, so we can work on our local host to write our code. For the sake of simplicity, we will just edit one file, README.md.

Of course, the first step consists of cloning the repository:

$ git clone git@gitlab.com:DAVEEmbeddedSystems/test/test0.git
Cloning into 'test0'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.

Then, we check out the branch named 1-first-release:

$ cd test0/
test0$ git branch -a
* master
  remotes/origin/1-first-release
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
test0$ git checkout 1-first-release 
Branch '1-first-release' set up to track remote branch '1-first-release' from 'origin'.
Switched to a new branch '1-first-release'
test0$ ll
total 12
drwxrwxr-x 3 llandre llandre 4096 ago 16 22:06 ./
drwxrwxr-x 3 llandre llandre 4096 ago 16 22:06 ../
drwxrwxr-x 8 llandre llandre 4096 ago 16 22:07 .git/
-rw-rw-r-- 1 llandre llandre    0 ago 16 22:06 README.md

We edit the README.md file with our favorite editor, then we commit our changes and push them to the remote repository:

test0$ git diff
diff --git a/README.md b/README.md
index e69de29..901353b 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1 @@
+This is the first release.
test0$ git add README.md 
test0$ git commit -m "Change README.md"
[1-first-release ce31afa] Change README.md
 1 file changed, 1 insertion(+)
test0$ git push
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (3/3), 277 bytes | 277.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: 
remote: View merge request for 1-first-release:
remote:   https://gitlab.com/DAVEEmbeddedSystems/test/test0/-/merge_requests/1
remote: 
To gitlab.com:DAVEEmbeddedSystems/test/test0.git
   e382410..ce31afa  1-first-release -> 1-first-release

On GitLab-side we can close the merge request. We mark it as ready in order to prepare it for merging:

In case you have permission to start the merging by yourself, you can press the "Merge" button. If you do not have such permission, for example because you have been assigned a developer role, this operation will be run by the maintainer of the repository on your behalf, possibly after reviewing your code.

After merging is complete, you should see something like this:

If we check the master branch, GitLab confirms that the merging was completed successfully:

We can also see a graphical representation of we just did: it is clear that the temporary branch was deleted after it had been merged into the master branch:

Conclusion

We strongly recommend to use this workflow for any implementation, being it adding a new feature, fixing a bug, optimizing a function, or whatever. Even though it may seem a little bit cumbersome at first sight, it has proved to be very efficient and effective when several developers are involved in the same project.