GitLab Workflow for OpenAirInterface TM:

Style Definition: Heading 3: Font: Bold

Style Definition: TOC 3: Tab stops: 6.49", Right,Leader: …

Contents
Contents.................................................................................................................................................. 1
1. Introduction .................................................................................................................................. 32
2. Branches........................................................................................................................................ 85
2.1. The main branches ................................................................................................................. 85
2.2. Supporting branches .............................................................................................................. 96
3. Gitlab workflow ........................................................................................................................... 106
3.1. Create GitLab Issue .............................................................................................................. 106
3.2. Naming of branches ............................................................................................................. 106
3.3. Repositories ......................................................................................................................... 107
3.4. Feature/Enhancement branches .......................................................................................... 117
Creating a feature branch ............................................................................................................ 128
Incorporating a finished feature on develop ................................................................................ 139
3.5. Release branches ................................................................................................................ 149
Creating a release branch ............................................................................................................ 159
Finishing a release branch .......................................................................................................... 1610
3.6. Hotfix branches .................................................................................................................. 1711
Creating the hotfix branch ......................................................................................................... 1812
Finishing a hotfix branch ............................................................................................................ 1913
4. Policy for Continuous Integration ............................................................................................... 2014
5. Requirements for Code Quality .................................................................................................. 2516
6. References................................................................................................................................. 2516
1.Introduction ......................................................................................................................................... 2
1.1.Create GitLab Issue: ....................................................................................................................... 5
2.The main branches .............................................................................................................................. 6
3.Supporting branches ............................................................................................................................ 7
3.1.Naming of branches ...................................................................................................................... 8
3.2.Feature/Enhancement branches ................................................................................................... 8
 3.3.Release branches ........................................................................................................................ 11
3.4.Hotfix branches ........................................................................................................................... 14
4.Note: Any merge to the development/master branch needs to pass GitLab-CI tests once it is
setup.Policy for Continuous Integration ................................................................................................. 17
5.Policy for Continuous Integration ....................................................................................................... 18
6.Requirements for Code Quality........................................................................................................... 18
7.References: ........................................................................................................................................ 18
 Formatted: Space Before: 0 pt, After: 10 pt, Line spacing:
Multiple 1.15 li, Pattern: Clear

1. Introduction
In this document, we describe the Git workflow adopted in OpenAirInterface (OAI). This workflow is Formatted: Space Before: 0 pt, After: 10 pt, Line spacing:
Multiple 1.15 li, Pattern: Clear
primarily based on [1]. However, we might make adaptations to it based on the needs of OAI.
Figure 1: Overview of OAI Workflow
Figure 1Figure 1 describes the overview of proposed OAI workflow. All the commits in the development
branch (see below for more detailed description on branching structure in OAI) should be referenced
with GitLab Issue tracking. Once the issue is identified, it is created in GitLab and assigned to the
developer. The developer then creates a feature-branch from the latest development-branch. Once, the
developer has finished the work, the next step is to clean-up history and organize commits. This can be
easily done using “rebase”. However, note that you can only use rebase if your branch is not pushed to
the GitLab server. The issues related to rebase is described in more detail here [2]. Once, that is done
the feature-branch is sent to Gitlab-CI server to pass continuous integration tests. Only after all the tests
have passed, the pull request is sent to the respective admin for the code-review. Once, the code review
is passed, admin makes a final merge into the development branch.
We request everyone to signoff at least their last commit using git –s.

We now describe the branching strategy and release management that is shown below.
 Formatted: Keep with next

Figure 2: Branching strategy and release management

 Formatted: Space After: 10 pt, Line spacing: Multiple 1.15
li, Pattern: Clear

1.1. Create GitLab Issue:

Please include as much information as possible to describe the issue, for example, logs, message thread Formatted: Left
URL for mailing list, etc. Please include the name of the GitLab branch on which this issue is solved
within the “GitLab Issue”. For issues related to bugfixes/hotfixes, it must include enough information
for reproducing the issue. For example: OS type (VM, Ubuntu xx.xx, 32/64 bit, Git Version, Git branch
information, etc and also the mailing list thread link which discusses the issue in detail).

The repository setup that we use and that works well with this branching model, is that with a central Formatted: Space After: 10 pt, Line spacing: Multiple 1.15
li, Pattern: Clear
“truth” repo located at https://gitlab.eurecom.fr/oai/openairinterface5g. Note that this repo is
Formatted: Default Paragraph Font, Font: (Default) Calibri,
only considered to be the central one (since Git is a DVCS, there is no such thing as a central repo at a 11 pt
technical level). We will refer to this repo as origin, since this name is familiar to all Git users.

Each developer pulls and pushes to origin. But besides the centralized push-pull relationships, each
developer may also pull changes from other peers to form sub teams. For example, this might be useful
to work together with two or more developers on a big new feature, before pushing the work in
progress to origin prematurely. In the figure above, there are sub-teams of Alice and Bob, Alice and
David, and Clair and David.

Technically, this means nothing more than that Alice has defined a Git remote, named bob, pointing to
Bob’s repository, and vice versa.
Note: Subteam fetches is a purely an option amongst developers. Our recommendation is to create their
branches in Gitlab@Eurecom.fr and push their changes onto the branches created at origin.

2. Branches
2.2.1. The main branches Formatted: Heading 2, No bullets or numbering

Formatted: Space Before: 0 pt, After: 10 pt, Line spacing:

Multiple 1.15 li, Pattern: Clear

At the core, the development model is greatly inspired by existing models out there. The central repo
holds two main branches with an infinite lifetime:

 master

 develop

The master branch at origin should be familiar to every Git user. Parallel to the master branch, another
branch exists called develop.
We consider origin/master to be the main branch where the source code of HEAD always reflects
a production-ready state.

We consider origin/develop to be the main branch where the source code of HEAD always reflects a
state with the latest delivered development changes for the next release. Some would call this the
“integration branch”. This is where any automatic nightly builds are built from.

When the source code in the develop branch reaches a stable point and is ready to be released, all of
the changes should be merged back into master somehow and then tagged with a release number. How
this is done in detail will be discussed further on.

Therefore, each time when changes are merged back into master, this is a new production release by
definition. We tend to be very strict at this, so that theoretically, we could use a Git hook script to
automatically build and roll-out our software to our production servers everytimeevery time there was a
commit on master.

3.2.2. Supporting branches Formatted: Heading 2, No bullets or numbering

Formatted: Space After: 10 pt, Line spacing: Multiple 1.15

li, Pattern: Clear
Next to the main branches master and develop, our development model will use a variety of supporting
branches to aid parallel development between team members, ease tracking of features, prepare for
production releases and to assist in quickly fixing live production problems. Unlike the main branches,
these branches always have a limited life time, since they will be removed eventually. Their removal can
be decided on a case-by-case basis amongst the developers.

The different types of branches we may use are:

 Feature branches

 Release branches

 Hotfix branches

Each of these branches have a specific purpose and are bound to strict rules as to which branches may
be their originating branch and which branches must be their merge targets.

By no means are these branches “special” from a technical perspective. The branch types are
categorized by how we use them. They are of course plain old Git branches.
3. Gitlab workflow Formatted: Font:
Formatted: Heading 1, Outline numbered + Level: 1 +
3.1. Create GitLab Issue Numbering Style: 1, 2, 3, … + Start at: 1 + Alignment: Left +
Aligned at: 0" + Indent at: 0.25"
Before starting any new development an issue should be created on the gitlab server
(https://gitlab.eurecom.fr/oai/openairinterface5g/issues).

Please include as much information as possible to describe the issue, for example, logs, message thread
URL for mailing list, etc. Please include the name of the GitLab branch on which this issue is solved
within the “GitLab Issue”. For issues related to bugfixes/hotfixes, it must include enough information
for reproducing the issue. For example: OS type (VM, Ubuntu xx.xx, 32/64 bit, Git Version, Git branch
information, etc and also the mailing list thread link which discusses the issue in detail).

Formatted: Heading 2, Line spacing: single, Pattern: Clear

3.1.3.2. Naming of branches

At a certain point, there will be lot of branches in the project. In order to provide easy correlation to Formatted: Space After: 10 pt, Line spacing: Multiple 1.15
li, Pattern: Clear
branch names to issue numbers in GitLab, each branch name in GitLab server should be named as
following:

Branch Type-Gitlab Issue ID-Issue Brief Description

For example, feature branch with Gitlab Issue ID of 12 and which fixes HARQ issue, should be named as:

Feature-12-fix_HARQ

Please also include the branch information in issue tracking system at Gitlab@Eruecom.fr
gitlab.eurecom.fr for easier search of branch name at a later stage.

3.3. Repositories Formatted: Heading 2

The repository setup that we use and that works well with this branching model, is that with a central
“truth” repo located at https://gitlab.eurecom.fr/oai/openairinterface5g. Note that this repo is
only considered to be the central one (since Git is a DVCS, there is no such thing as a central repo at a
technical level). We will refer to this repo as origin, since this name is familiar to all Git users.

This central repository should only contain the main branches master and develop and maybe some
long-term development branches. Feature/hotfix/bugfix branches should not be pushed onto this
central repository. These branches should either be pushed to a private fork of the repository or the
repository located at https://gitlab.eurecom.fr/oai-internal/openairinterface5g. Private forks of the
central repository can also be shared with other developers using the gitlab interface.

Additional repositories can be added to your local git working directory using the “git remote add”
command. Make sure that you push your branch to the right repository when using the “git push”
command. See git help for more details.

Formatted: Heading 2, Line spacing: single, Pattern: Clear

3.2.3.4. Feature/Enhancement branches

Formatted: Space Before: 0 pt, After: 10 pt, Line spacing:

Multiple 1.15 li, Pattern: Clear

May branch off from:

develop

Must merge back into:

develop

Branch naming convention:

anything except master, develop, release-*, or hotfix-*

anything except master, develop, release-*, or hotfix-*
Feature branches (or sometimes called topic branches) are used to develop new features for the
upcoming or a distant future release. When starting development of a feature, the target release in
which this feature will be incorporated may well be unknown at that point. The essence of a feature
branch is that it exists as long as the feature is in development, but will eventually be merged back
into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a
disappointing experiment).

Feature branches are created in origin so multiple developers can push to the same feature branch
with some coordination amongst each other.

Creating a feature branch

When starting work on a new feature, branch off from the latest develop branch.

$ git fetch origin

$ git checkout -b myfeature origin/develop

Switched to a new branch "myfeature"

Committing

Now you can start working on your branch. Commit your code regularly and use commit messages to
describe your changes. A single commit should not contain too many changes at the same time.

If your development takes longer, make sure to synchronize regularly with origin/develop using

$ git fetch origin

$ git merge origin/develop

Your last commit message should contain mention that it closes issue x, where x is the issue ID. You
should use one of the following patterns :
https://gitlab.eurecom.fr/help/user/project/issues/automatic_issue_closing.md. This should
automatically close the issue on gitlab, once merged back to develop.

Pushing
To have a backup, to collaborate with other people, or to create a merge request, you should push your
code also regularly to the gitlab server, either in your local clone of the repository or into the oai-
internal repository (see Section 3.3). Feature branches should not be pushed to the main oai repository.

$ git push myremote myfeature

Incorporating a finished feature on developMerge request

Before a branch can be merged back into develop, the Gitlab CI tests that must be passed, please refer
to https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/OAITestSetup.

Once a branch is finished and ready to be merged back into develop, a merge request needs to be
created in gitlab (https://gitlab.eurecom.fr/oai/openairinterface5g/merge_requests,
https://gitlab.eurecom.fr/oai/openair-cn/merge_requests). Merge requests can also be created from
different repositories if they were properly forked before (e.g. using the fork button in gitlab).

Merge requests are then handled by the OAI team as described in Section 45.

Formatted: Heading 2, Left, Line spacing: single, Pattern:

Clear, Tab stops: Not at 0.64" + 1.27" + 1.91" + 2.54" +
3.18" + 3.82" + 4.45" + 5.09" + 5.73" + 6.36" + 7" +
7.63" + 8.27" + 8.91" + 9.54" + 10.18"

Finished features may be merged into the develop branch definitely add them to the
upcoming release:

$ git checkout develop

Switched to branch 'develop'

$ git merge --no-ff myfeature

Updating ea1b82a..05e9557

(Summary of changes)

$ git branch -d myfeature

Deleted branch myfeature (was 05e9557).

$ git push origin develop Commented [FK1]: I don’t think that deletes the branch
remotely. You have to do git push origin –delete myfeature
 The --no-ff flag causes the merge to always create a new commit object, even if the
merge could be performed with a fast-forward. This avoids losing information
about the historical existence of a feature branch and groups together all commits
that together added the feature. Compare:

In the latter case, it is impossible to see from the Git history which of the commit
objects together have implemented a feature—you would have to manually read all
the log messages. Reverting a whole feature (i.e. a group of commits), is a true
headache in the latter situation, whereas it is easily done if the --no-ff flag was
used.

It will create a few more (empty) commit objects, but the gain is much bigger that
that cost.

Note: Any merge to the development/master branch needs to pass GitLab-CI tests
once it is setup.

3.3.3.5. Release branches Commented [FK2]: not really used at the moment

May branch off from: Formatted: Space After: 10 pt, Line spacing: Multiple 1.15
li, Pattern: Clear
develop

Must merge back into:

Develop and and master

Branch naming convention:

release-*

Release branches support preparation of a new production release. They allow for last-minute dotting of
i’s and crossing t’s. Furthermore, they allow for minor bug fixes and preparing meta-data for a release
(version number, build dates, etc.). By doing all of this work on a release branch, the develop branch is
cleared to receive features for the next big release.

The key moment to branch off a new release branch from develop is when develop (almost) reflects the
desired state of the new release. At least all features that are targeted for the release-to-be-built must
be merged in to develop at this point in time. All features targeted at future releases may not—they
must wait until after the release branch is branched off.

It is exactly at the start of a release branch that the upcoming release gets assigned a version number—
not any earlier. Up until that moment, the develop branch reflected changes for the “next release”, but
it is unclear whether that “next release” will eventually become 0.3 or 1.0, until the release branch is
started. That decision is made on the start of the release branch and is carried out by the project’s rules
on version number bumping.

Creating a release branch

Release branches are created from the develop branch. For example, say version 1.1.5 is the current
production release and we have a big release coming up. The state of develop is ready for the “next
release” and we have decided that this will become version 1.2 (rather than 1.1.6 or 2.0). So we branch
off and give the release branch a name reflecting the new version number:

$ git checkout -b release-1.2 develop

Switched to a new branch "release-1.2"

$ ./bump-version.sh 1.2

Files modified successfully, version bumped to 1.2.

$ git commit -a -m "Bumped version number to 1.2"

[release-1.2 74d9424] Bumped version number to 1.2

1 files changed, 1 insertions(+), 1 deletions(-)

After creating a new branch and switching to it, we bump the version number. Here, bump-version.sh is
a fictional shell script that changes some files in the working copy to reflect the new version. (This can of
course be a manual change—the point being that some files change.) Then, the bumped version number
is committed.

This new branch may exist there for a while, until the release may be rolled out definitely. During that
time, bug fixes may be applied in this branch (rather than on the develop branch). Adding large new
features here is strictly prohibited. They must be merged into develop, and therefore, wait for the next
big release.

Finishing a release branch

When the state of the release branch is ready to become a real release, some actions need to be carried
out. First, the release branch is merged into master (since every commit on master is a new release by
definition, remember). Next, that commit on master must be tagged for easy future reference to this
historical version. Finally, the changes made on the release branch need to be merged back
into develop, so that future releases also contain these bug fixes.

The first two steps in Git:

$ git checkout master

Switched to branch 'master'

$ git merge --no-ff release-1.2

Merge made by recursive.

(Summary of changes)

$ git tag -a 1.2

$ git push

The release is now done, and tagged for future reference.

To keep the changes made in the release branch, we need to merge those back into develop, though. In
Git:

$ git checkout develop

Switched to branch 'develop'

$ git merge --no-ff release-1.2

Merge made by recursive.

(Summary of changes)

$git push

This step may well lead to a merge conflict (probably even, since we have changed the version number).
If so, fix it and commit.

Now we are really done and the release branch may be removed, since we don’t need it anymore:

$ git branch -d release-1.2

Deleted branch release-1.2 (was ff452fe).

$ git push origin --delete release-1.2

Note: Any merge to the development/master branch needs to pass GitLab-CI tests once it is setup.

3.4.3.6. Hotfix branches

 Formatted: Space Before: 0 pt, After: 10 pt, Line spacing:
Multiple 1.15 li, Pattern: Clear

May branch off from:

master

Must merge back into:

Develop and and master

Branch naming convention:

hotfix-*

Hotfix branches are very much like release branches in that they are also meant to prepare for a new
production release, albeit unplanned. They arise from the necessity to act immediately upon an
undesired state of a live production version. When a critical bug in a production version must be
resolved immediately, a hotfix branch may be branched off from the corresponding tag on the master
branch that marks the production version.

The essence is that work of team members (on the develop branch) can continue, while another person
is preparing a quick production fix.

Creating the hotfix branch

Hotfix branches are created from the master branch. For example, say version 1.2 is the current
production release running live and causing troubles due to a severe bug. But changes on develop are
yet unstable. We may then branch off a hotfix branch and start fixing the problem:

$ git checkout -b hotfix-1.2.1 master

Switched to a new branch "hotfix-1.2.1"

$ ./bump-version.sh 1.2.1

Files modified successfully, version bumped to 1.2.1.

$ git commit -a -m "Bumped version number to 1.2.1"

[hotfix-1.2.1 41e61bb] Bumped version number to 1.2.1

1 files changed, 1 insertions(+), 1 deletions(-)

Then, fix the bug and commit the fix in one or more separate commits.

$ git commit -m "Fixed severe production problem"

[hotfix-1.2.1 abbe5d6] Fixed severe production problem

5 files changed, 32 insertions(+), 17 deletions(-)

Finishing a hotfix branch

When finished, the bugfix needs to be merged back into master, but also needs to be merged back
into develop, in order to safeguard that the bugfix is included in the next release as well. This is
completely similar to how release branches are finished.

First, update master and tag the release.

$ git checkout master

Switched to branch 'master'

$ git merge --no-ff hotfix-1.2.1

Merge made by recursive.

(Summary of changes)

$ git tag -a 1.2.1

$ git push

Next, include the bugfix in develop, too:

$ git checkout develop

Switched to branch 'develop'

$ git merge --no-ff hotfix-1.2.1

Merge made by recursive.

(Summary of changes)

$ git push

The one exception to the rule here is that, when a release branch currently exists, the hotfix changes
need to be merged into that release branch, instead of develop. Back-merging the bugfix into the
release branch will eventually result in the bugfix being merged into develop too, when the release
branch is finished. (If work in develop immediately requires this bugfix and cannot wait for the release
branch to be finished, you may safely merge the bugfix into develop now already as well.)

Finally, remove the temporary branch:

$ git branch -d hotfix-1.2.1

Deleted branch hotfix-1.2.1 (was abbe5d6).

$ git push origin --delete hotfix-1.2.1

4. Policy for Continuous Integration

For Gitlab CI tests that must be passed before merging branch, please refer to
https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/OAITestSetup
Note: Any merge to the development/master branch needs to pass GitLab-CI tests. Formatted: Space Before: 0 pt, After: 10 pt, Line spacing:
Multiple 1.15 li, Pattern: Clear

Merging Branches (FINAL STEP)

When merging branches, please create a merge request in gitlab

(https://gitlab.eurecom.fr/oai/openairinterface5g/merge_requests,
https://gitlab.eurecom.fr/oai/openair-cn/merge_requests ) and then delete the branch if it will not be
used in future. Please merge the branch from gitlab interface.
5. Policy for Continuous Integration
The work flow integration will done on a weekly basis period. Each week a new tag is set on the develop
branch. The tag is the guarantee that no regression was made: before each tag we run a non-regression
test campaign and make sure that both UE + eNB are not broken.

Each time you start a new development, you need to create your new branch based on latest tag (from
develop branch).

Here the work flow process:

1- Each Thursday, the integrator will collect the list of all potential commits that are ready to be
merged to develop branch. The list is driven from the merge request on git lab.
2- Create a temporary integration branch based on latest tag from develop.
3- Merge all potential commits into integration branch.
4- Run non regression tests on both UE + eNB
a. The test campaign is PASS  push all commits into develop branch and set a new TAG.
b. The test campaign is FAIL, determine the potential commit causing the failure (using
dichotomy method) and exclude it from the integration branch. Re-run the test
campaign and make sure that the test are PASS (if not, re do the same step):  push
PASS commits into develop branch and set a new TAG

Please refer to the following two diagrams that explain the work flow process:
6.5. Requirements for Code Quality

We have all agreed in one of our group meetings to indent the files which are part of commit (See
conding guidelines for indenting code automatically). Also, all the files that will be submitted as part of
merge request need to be commented (at least high level functions) which show up in system
architecture document (for eNB, it is done aleady, for UE it is pending) and that these comments appear
in doxygen correctly. This one small step will hopefully improve the code quality in future.

7.6. References:

[1] http://nvie.com.posts/a-successful-git-branching-model

[2] https://about.gitlab.com/2014/09/29/gitlab-flow.