|
|
<table style="border-collapse: collapse; border: none;">
|
|
|
<tr style="border-collapse: collapse; border: none;">
|
|
|
<td style="border-collapse: collapse; border: none;">
|
|
|
<a href="http://www.openairinterface.org/">
|
|
|
<img src="../images/oai_final_logo.png" alt="" border=3 height=50 width=150>
|
|
|
</img>
|
|
|
</a>
|
|
|
</td>
|
|
|
<td style="border-collapse: collapse; border: none; vertical-align: center;">
|
|
|
<b><font size = "5">OAI Software Alliance Branch Policy</font></b>
|
|
|
</td>
|
|
|
</tr>
|
|
|
</table>
|
|
|
|
|
|
## Table of Contents ##
|
|
|
|
|
|
1. [Main branches](#1-main-branches)
|
|
|
2. [Feature branches](#2-feature-branches)
|
|
|
1. [Creation of a feature branch](#21-creation-of-a-feature-branch)
|
|
|
2. [Committing](#22-committing)
|
|
|
3. [Pushing into the central repository](#23-pushing-into-the-central-repository)
|
|
|
3. [Bug-fix branches](#3-bug-fix-branches)
|
|
|
4. [Inactives branches](#4-inactives-branches)
|
|
|
|
|
|
----
|
|
|
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:
|
|
|
* master
|
|
|
* 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.
|
|
|
* develop
|
|
|
* 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”.
|
|
|
|
|
|
<img src="../images/master-dev-branches.png" width = "267" height = "402" align = "center" />
|
|
|
|
|
|
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.
|
|
|
|
|
|
<img src="../images/feature-branches.png" width = "133" height = "357" align = "center" />
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
```bash
|
|
|
# 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
|
|
|
```
|
|
|
|
|
|
## 2.2. 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.
|
|
|
* Every commit **SHALL** be signed.
|
|
|
|
|
|
```bash
|
|
|
# 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:
|
|
|
|
|
|
```bash
|
|
|
$ 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.
|
|
|
|
|
|
```bash
|
|
|
$ 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.
|
|
|
|
|
|
```bash
|
|
|
$ git push origin feat-0001-my-example
|
|
|
```
|
|
|
|
|
|
In case of problem, you may have to force the push:
|
|
|
|
|
|
```bash
|
|
|
$ 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).
|
|
|
|
|
|
# 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.
|
|
|
|
|
|
<img src="../images/bugfix-branch.png" width = "316" height = "426" align = "center" />
|
|
|
|
|
|
* 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. |