RidgeRun Developer Manual - Methodologies - Gitflow

About Gitflow Methodologies

A "gitflow" methodology is no more than a set of practices that define the workflow for software development involving a version control system like git. RidgeRun follows a "homegrown" methodology based on the feature branch model. This model has several advantages:

It is very well suited for projects scheduled on release cycles.
Allows to maintain a stable code base for all developers involved after each release, which synergizes very well with continuous integration practices.
Feature branches allow to implement a pull request, a type of code review.
Feature development isolation. Each developer works on its branch and does not affect the development of other branches by other developers.
There are very well defined roles for a git branch, for example, there is the development branch, the master branches, the hotfix branches, etc.

Overview

The RidgeRun git workflow can be summarized in the figure below:

The process goes as follows:

The project starts with a single commit in the main branch, from where the develop branch is started.
From the develop branch, developers branch out features , which eventually get merged back into develop.
Eventually, when the time comes, a new release branch is branched out from develop. The release branch is tested thoroughly and, when ready, is merged into main and into develop.
The merge into main is considered a release and must be tagged accordingly.
The process repeats from point 2.
If eventually a critical issue is found on the main branch, a hotfix is branched out from it, fixed, and merged back into main and develop .

Concepts

Initial commit

The content is typically a README.md containing a description of the project.
The typical commit message is:

Initialize project.

Main branch

Formerly called "master".
It is always stable, i.e: should always build and run.
Never do a commit directly in this branch.
Never allowed to do forced push ( git push -f ) on it.

Initial develop commit

Purely aesthetic.
Created with:

git commit --allow-empty -m "Initialize develop"

Develop branch

Contains the latest development state.
It is always stable, i.e: should always build and run (tests must pass as well).
May not be in perfect shape (mid refactor, for example).
Never do commits directly.
Never do forced push ( git push -f ) on it.

Feature branch

Are named as feature/xxx-xxx-xxx .
Name should complete: This feature will _______.
Uses hyphens to separate words.
Minimum change that generates value by itself.
Don't turn it into another develop branch (infinite extension).
No overlapping features:

Every branch should be rebased to avoid overlaps between features (see Rebasing feature branches section).
First merge (after approval) gets priority.
It is completely okay to have a single commit feature branch.

Release branch

Are named as release/v0.1.0
Should contain at least a commit that adjusts the version number.
Merges into main and develop.
Should not block the develop branch.

Hotfix branch

Used to perform a critical fix in main (it cannot wait for the next release).
Named hotfix/xxx-xxx-xxx.
Name should complete: This hotfix will _______.
Should contain at least a commit that adjusts the version number.
Is branched from main.
Merges into main and develop.
Should not block the develop branch.

Feature, Release and Hotfix Merges

Should follow the Conventional Commit standard.
Helps to auto generate release notes.
Should always be done with non-fast-forward option as in the following:

git checkout develop
git merge --no-ff feature/refactor-ui-to-mvc

Release merges

Must contain an annotated tag.
If the hosting serving allows it, it must be accompanied with release notes.
The typical message is:

Release v0.1.0 includes:
* Support for feature X
* Fix for bug Y

Some particular considerations on the feature branch model

Rebasing feature branches

Let's assume this scenario, person A and person B are working in parallel each one on individual feature branches that diverged from the same commit in the development branch. Now, let's assume person A got his/her feature branch approved first than person B. Once person A merges the feature branch in the development branch, person A should tell person B that he/she needs to rebase his/her feature branch, so person B can follow these commands:

 git fetch # update you local repo from the remote repo
 git checkout develop
 git pull
 git checkout feature/person-b-feature
 git rebase develop # This may arise merge conflicts that have to be solved
 #Do your commit: git add, git commit...
 git push -f

The following figure illustrates this process:

But why rebasing features branches is required? There are several reasons to it:

Makes it easier to track issues in the development branch, since this branch will have clear points where the feature branches were merged (see Merging feature branches).
Each developer will have the latest code base in its local repo which implicitly allows for testing the feature that was originally developed in another system. Sometimes this helps find issues.

Merging feature branches

Features must be merged in "non-fast-forward" mode which tells git to construct a merge commit instead of a "fast forward" operation. This is a crucial decision that RidgeRun follows in their methodology in order to maintain a well defined git network topology (figure below illustrates this). One of the main advantages is that it allows keeping a development branch clean, well organized, easy to follow and to track issues. An example set of commands is shown:

 git checkout develop
 git merge --no-ff feature/awesome-feature # Creates merge commit

Commit messages standard

Our preferred standard for commit messages is a "homegrown" variant of Conventional Commits.

Versioning standard

We encourage the use of Semantic Versioning.

Previous: Methodologies

Index

Next: Methodologies/Project Cycles

❯