MISC-TN-028: GitLab-based workflow

From DAVE Developer's Wiki
Jump to: navigation, search
Info Box


History[edit | edit source]

Version Notes
August 2023 First public release

Introduction[edit | edit source]

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[edit | edit source]

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:

Gitlab-wf-1.png

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.

Gitlab-wf-2.png

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.

Gitlab-wf-3.png

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
Gitlab-wf-4.png

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

Gitlab-wf-5.png

In case you have permission to start 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.

Gitlab-wf-6.png

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

Gitlab-wf-7.png

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

Gitlab-wf-8.png

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:

Gitlab-wf-9.png

Conclusion[edit | edit source]

It is strongly recommended to use this workflow for any implementation, be 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.