At the core of SW development under Git, there are branches.
1. Main branches
Any OAI Git repository holds two (2) main branches with an infinite lifetime:
The master branch at origin should be familiar to every Git user.
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”.
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 details will be discussed further on.
2. Feature branches
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).
These branches always have a limited life time.
Feature branches are created in origin so multiple developers can push to the same feature branch with some coordination amongst each other.
May branch off from develop
Must merge back into develop
Branch naming convention: feat-****
if a ticket has been opened for this feature, it should be refered in branch name: feat-0012-****
2.1. Creation of a feature branch
When starting work on a new feature, branch off from the latest develop branch.
# Retrieve the latest version of code$ git fetch origin# Create a feature branch on the latest develop$ git checkout -b feat-0001-my-example# Now you are switched to the new branch
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.
Every commit SHALL be signed.
# back into the feature branch$ git checkout feat-0001-my-example# add new file(s) and commit with a proper message$ git add newfile# commit should be signed$ git commit -s
If your development takes longer, make sure to synchronize regularly with origin/develop using:
$ git checkout feat-0001-my-example# Retrieve the latest and rebase the feature branch with develop$ git fetch origin$ git rebase origin/develop
However you may have forgotten to do the rebase for a long time. The git rebase process is replaying all the commits from the develop branch.
In case of merge conflicts, it can be painful because you may have to resolve conflicts several times. The rebase will stop each time you have a conflict, you need to resolve it manually and then continue the rebase. In that case it certainly better (not necesserily easy) to resolve merge conflicts at once.
$ git checkout feat-0001-my-example# Retrieve the latest from develop and merge into feature branch$ git fetch origin$ git merge -s recursive -Xpatience origin/develop
IT IS THE DEVELOPER/CONTRIBUTOR'S RESPONSABILITY TO PERFORM REGULAR MERGES ONTO ITS FEATURE BRANCH
2.3. Pushing into the central repository
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/github server.
$ git push origin feat-0001-my-example
In case of problem, you may have to force the push:
$ git push --force origin feat-0001-my-example
2.4. Contributing to the main branch (aka develop)
Merge Requests are the way to push your feature contributions into the main develop branch.
Since a merge request opening triggers the Continuous Integration process, a lot of validations is automatically performed for a Merge Request to be accepted.
However there is still a human factor: code review. One or several Technical Committee member(s) will read your contributions and provide feedback.
For their work to be easier, it is strongly recommended that feature branches development proceeds by small merge requests. Their list of modified files would be limited and won't break the existing features. It will be easier to review.
It will also allow CI administrator(s) to prepare the integration of new tests to validate the new feature(s).
2.5. Contributing to Testing
You are adding code / feature to the OAI project. Nice but that's half the work! Feature without testing is no feature.
The Continuous Integration process DO prevent new contributions to:
Break existing features that are tested by the current test-suite
Degradate existing features' performances that are measured by the current test-suite
But the CI process DOES NOT prevent other contributors to:
Break / Degradate your brand new merged feature(s)
If you don't contribute to the CI test suite
Testing your brand new feature can be done several ways:
Unit-level testing: a little program is build and auto-tests itself
There are several simulator-based frameworks
There is a Python-based framework when testing with COTS (real) UEs
You should ask yourselves the best way to test your new feature(s).
In any case, you should communicate with the OAI CI team in order to have your tests included in the official OAI CI test-suite.
You should provide (the list is not exhaustive):
Build variant to use (in another words, which option(s) to use)
Do you need equipement?
3. Bug-fix branches
Bug-fix 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 bug-fix 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.
Bug-fix branches SHALL be deleted once the bug fix has been integrated to master / develop branches and validated through Continuous Integration.
May branch off from master or develop
Must merge back into develop and/or master
Branch naming convention: fix-XXXX-****
A ticket SHALL HAVE BEEN opened for this issue
The ticket ID SHALL be refered in branch name: fix-0012-****
4. Inactives branches
Inactive branch is a branch derived from master or develop with a few commits, with the latest being a few monthes old.
At some point, OAI admin will contact the branch owner and ask to either contribute or the branch will be deleted from the central repository.