|
|
<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>
|
|
|
<tr>
|
|
|
<td>
|
|
|
|
|
|
</td>
|
|
|
<td>
|
|
|
|
|
|
**OAI Software Alliance Branch Policy**
|
|
|
</td>
|
|
|
</tr>
|
|
|
</table>
|
|
|
|
|
|
## Table of Contents ##
|
|
|
## Table of Contents
|
|
|
|
|
|
1. [Main branches](#1-main-branches)
|
|
|
2. [Feature branches](#2-feature-branches)
|
... | ... | @@ -24,38 +22,48 @@ |
|
|
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 #
|
|
|
# 1. Main branches
|
|
|
|
|
|
Any OAI Git repository holds two (2) main branches with an infinite lifetime:
|
|
|
|
|
|
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”.
|
|
|
* 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" />
|
|
|
![](../images/master-dev-branches.png)
|
|
|
|
|
|
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 #
|
|
|
## 1.1. Merge Request branches naming conventions
|
|
|
|
|
|
For the following sections, all of these branches will have a purpose to go through the CI process. Currently our OAI CI process is using a `docker-registry` scheme and we are using the source branch name from your merge request to create a `docker` image name.
|
|
|
|
|
|
Due to this scheme, your branch name SHALL not be constructed following a `username/my-branch-name`. It will result in a failure during build process.
|
|
|
|
|
|
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.
|
|
|
If you want to add your `username` to your branch name, please use `username_my-branch-name` or `username-my-branch-name` as naming convention.
|
|
|
|
|
|
# 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" />
|
|
|
![](../images/feature-branches.png)
|
|
|
|
|
|
* 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-****`
|
|
|
* 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
|
|
|
|
|
|
## 2.1. Creation of a feature branch ##
|
|
|
When starting work on a new feature, branch off from the latest `develop` branch.
|
|
|
|
|
|
```bash
|
... | ... | @@ -66,8 +74,10 @@ $ 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.
|
|
|
## 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.
|
... | ... | @@ -81,7 +91,7 @@ $ git add newfile |
|
|
$ git commit -s
|
|
|
```
|
|
|
|
|
|
If your development takes longer, make sure to synchronize regularly with `origin/develop` using:
|
|
|
If your development takes longer, make sure to synchronize regularly with `origin/develop` using:
|
|
|
|
|
|
```bash
|
|
|
$ git checkout feat-0001-my-example
|
... | ... | @@ -103,7 +113,7 @@ $ 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 ##
|
|
|
## 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.
|
|
|
|
... | ... | @@ -117,7 +127,7 @@ 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`) ##
|
|
|
## 2.4. Contributing to the main branch (aka `develop`)
|
|
|
|
|
|
Merge Requests are the way to push your feature contributions into the main `develop` branch.
|
|
|
|
... | ... | @@ -129,25 +139,25 @@ For their work to be easier, it is strongly recommended that feature branches de |
|
|
|
|
|
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 ##
|
|
|
## 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
|
|
|
* 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**
|
|
|
* 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
|
|
|
* 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).
|
|
|
|
... | ... | @@ -155,28 +165,28 @@ In any case, you should communicate with the OAI CI team in order to have your t |
|
|
|
|
|
You should provide (the list is not exhaustive):
|
|
|
|
|
|
* Build variant to use (in another words, which option(s) to use)
|
|
|
* Server configuration
|
|
|
* Do you need equipement?
|
|
|
* Build variant to use (in another words, which option(s) to use)
|
|
|
* Server configuration
|
|
|
* Do you need equipement?
|
|
|
|
|
|
# 3. Bug-fix branches #
|
|
|
# 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 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" />
|
|
|
![](../images/bugfix-branch.png)
|
|
|
|
|
|
* May branch off from `master` or `develop`
|
|
|
* Must merge back into `develop` and/or `master`
|
|
|
* Branch naming convention: `fix-XXXX-****`
|
|
|
* 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-****`
|
|
|
* The ticket ID **SHALL** be refered in branch name: `fix-0012-\*\*\*\*`
|
|
|
|
|
|
# 4. Inactives branches #
|
|
|
# 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. |
|
|
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. |
|
|
\ No newline at end of file |