Branching Model

Branching Strategy and Release Management for WIA

Introduction

This GitHub wiki page outlines the guidelines for the branching strategy and release management for our group project. The purpose of a well-defined branching strategy is to maintain a clean and organized codebase and facilitate collaboration between team members. This document provides an overview of the main branches and supporting branches, along with the specific rules and conventions that govern their usage.

Glossary

• Git: A version control system used to manage changes to codebase and collaborate with others.
• Repository (repo): A central location where the source code for a project is stored.
• Branch: A parallel version of the codebase that enables separate development and experimentation without affecting the main codebase.
• Main branch: The primary branch in a Git repository where the source code reflects a production-ready state.
• Dev branch: The primary branch in a Git repository where the source code reflects a state with the latest delivered development changes for the next release.
• Origin: A shorthand name for the remote repository from which a local repository was cloned.
• Merge: The integration of changes from one branch into another.
• Tag: A way to mark a specific point in Git history as being important, typically used to mark releases.
• Feature branch: A branch created off of the develop branch to develop a new feature for an upcoming or future release.
• Release branch: A branch created off of the develop branch to prepare for a new release.
• Hotfix branch: A branch created off of the main branch to quickly fix a critical bug or issue in production.

Main Branches

• main: The origin/main is the main branch where the source code always reflects a production-ready state.
• dev: The origin/dev is the main branch where the source code always reflects a state with the latest delivered development changes for the next release. Some refer to this as the “integration branch”. Automatic nightly builds are built from this branch.

When the source code in the develop branch is stable and ready to be released, all changes should be merged back into main and tagged with a release number. This is further discussed in the "Release Branches" subsection.

Branch Organization

Projects

As main and dev branches are our collaborated project branches, we need separation for different projects (practice-app and web-info-aggregator). To achieve this separation in our branch system, branch names will start with [PROJECT]/... and will continue with team information or supporting branch information depending on the project. For the practice-app, as there are no separated teams, branch name will continue with supporting branches directly, however, for the web-info-aggregator project, different teams must be indicated first.

Teams

For the web-info-aggregator project, we need separation for different teams (backend, frontend and mobile). To achieve this separation branch names will continue with .../[TEAM]/... after project information. Branch name will further continue with supporting branch information. Every team will have a master branch that will be named as /[PROJECT]/[TEAM]/master-[TEAM]. The master branch will serve to assemble different supporting branches of the team.

Supporting Branches

Apart from the project and team separation, all branches will continue with supporting branches information. Our development model uses several supporting branches to enable parallel development between members, track features, and address live production issues. These branches have a limited lifespan as they will eventually be removed.

The different types of branches we may use are:

• Feature Branches

Feature branches are used to develop new features for the upcoming or a distant future release. When starting development of a feature, the target release may be unknown. A feature branch exists as long as the feature is in development, but will eventually be merged back into dev to add the new feature to the upcoming release or discarded if it is not satisfactory.

May branch off from:

dev master-<TEAM>

Must merge back into:

dev master-<TEAM>

Branch name will continue with .../feature/<TITLE>-

The pull request should include a link to the issue that the branch is open for and can be opened as soon as changes are pushed to origin.

Issues about the codebase should be created considering the feature branching policy in place. Each issue should correspond to one feature branch. So codebase issues should not be over inflated, thus allowing meaningful progress in the dev branch. To link issues with branches and commits, either use the issue link in your commit message, or add a link to the commit in the issue as a comment. This is not required but is very appreciated. Issues should be closed when the feature branch is merged into dev, or if the feature is not required anymore and no further work will be done on the branch. These branches should be pushed to origin and linked to the issue and pull requests should be created as soon as changes are made on the branch. The pull request and issue should also be linked together for easy access.

• Fix Branches

Fix branches are used to fix issues in existing or completed components in production.

May branch off from:

dev master-<TEAM>

Must merge back into:

dev master-<TEAM>

Branch name will continue with .../fix/<TITLE>-

Release Branches

Release branches are used to prepare for a new production release. They allow for last-minute adjustments, minor bug fixes, and preparing metadata for a release (version number, build dates, etc.). By doing all this work on a release branch, the develop branch is freed to receive features for the next release.

May branch off from:

dev

Must merge back into:

dev and main

A new release branch should be created from develop when it almost reflects the desired state of the new release, with all features that are targeted for the release-to-be-built merged in to develop. All features targeted at future releases must wait until after the release branch is created.

At the start of a release branch, the upcoming release is assigned a version number. Version number bumping is done in increments of 0.1. For example, the initial release will be release-0.1, and release-0.2 for the next one, etc. The version number may change based on the requirements of the release and its impact on the application state.

Branch naming convention: release-<VERSION>

Hotfix Branches

While team members continue working on the dev or one of the master branches, another person can prepare a quick production fix using a hotfix branch.

May branch off from:

main

Must merge back into:

dev and main

A new version number is required for the merge into main, obtained by incrementing the current version by 0.0.1.

Branch naming convention: hotfix-<VERSION>

Hotfix branches are not frequently used but included in this guide for completeness.

Lastly

A well-defined branching strategy and release management guidelines can help to maintain a clean and organized codebase and facilitate collaboration between team members. The main branches (main and dev), supporting branches (feature and fix), release branches and hotfix branches have specific rules and conventions that govern their usage. It is important to follow these guidelines to ensure consistency and efficiency in the development process.

By implementing this branching strategy and release management, we can achieve the following benefits:

• Efficient collaboration between team members
• Easy tracking of features and preparation for production releases
• Ability to quickly fix live production problems
• Consistent and organized codebase
• Improved overall quality of the code

Following this guide will help us to ensure that our development process is streamlined, consistent, and efficient.