|
|
![logo](../images/oai_final_logo.png)
|
|
|
|
|
|
---
|
|
|
|
|
|
# OAI Software Alliance Branch Policy #
|
|
|
|
|
|
----
|
|
|
|
|
|
## 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)
|
|
|
|
|
|
----
|
|
|
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”.
|
|
|
|
|
|
![master develop](../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 #
|
|
|
|
|
|
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.
|
|
|
|
|
|
![feature](../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-****`
|
|
|
|
|
|
## 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
|
|
|
$ 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 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.
|
|
|
|
|
|
```bash
|
|
|
$ git push 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.
|
|
|
|
|
|
![feature](../images/bugfix-branch.png)
|
|
|
|
|
|
* 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-****` |