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 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
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-****