Git Branching Strategy for Feature Development and Production

Introduction

Git branching strategies are critical to ensuring a smooth software development lifecycle. Yet, many teams struggle with branch merging, particularly when it comes to moving features from development to production. A common issue arises when unfinished or partially tested features accidentally make their way into production, causing bugs, downtime, or misalignment between environments.

In this tutorial, we’ll explore an effective Git branching and merging strategy to solve these problems. Whether you’re a junior or senior software engineer, this guide will walk you through a structured approach that keeps your branches in sync while ensuring only fully developed features are deployed to production.

The Problem

The typical workflow goes something like this: you have multiple branches for dev, staging (QA), and production (master). Feature branches are developed off the dev branch, and after the feature is completed, it’s merged back into dev. The problem arises when dev contains unfinished or untested features, which eventually find their way into stage and production branches, causing disruptions in your production environment.

This happens because of inadequate isolation of features and lack of controlled syncing between branches. So, how can we ensure only fully tested and developed features are promoted to production while keeping all branches synchronized?

Solution: An Optimized Git Branching Strategy

We can adopt a strategy that separates dev, stage, and production environments while maintaining a consistent flow of stable features. Let’s break it down.

Branching Structure

Below is a diagram illustrating the branching structure, where features start from stage, get tested in dev, and are eventually merged into production:

1. Dev Branch:
   The dev branch is the integration point where feature branches are first merged. This branch allows the frontend engineers and other team members to work with the most recent API changes and developments without affecting the stage or production environments.
2. Stage Branch:
   The stage branch is for fully developed and tested features. This branch is a staging ground where features are polished and finalized before they are promoted to production. No unfinished or partially tested features should be present in this branch.
3. Production Branch:
   The production (also called master) branch holds the code that is currently deployed in the production environment. Only fully stable and tested features reach this branch.

Feature Branches

Developers create feature branches for each individual task or feature they are working on. These branches are isolated from the main development branches until the feature is ready to be merged.

Merging Process: Step-by-Step Guide

Here’s the step-by-step process to ensure smooth and controlled promotion of features across environments:

1. Developing a Feature

• Start from Stage: Create a feature branch off the stage branch, not the dev branch. This ensures that your feature builds upon stable code that has already been tested.

git checkout stage
git checkout -b feature/new-feature

2. Testing the Feature in Dev

Once you’ve finished the development of your feature, you’ll want to merge it into the dev branch for early testing. This step allows frontend engineers to start consuming your APIs or feature and helps identify any integration issues early on.

git checkout dev
git merge feature/new-feature

At this point, your feature is available for internal testing, but it hasn’t yet been finalized for release to production.

3. Finalizing the Feature in Stage

After the feature has been tested in the dev branch and you’re confident it is ready, the next step is to promote it to the stage branch. This branch should only include fully tested and completed features.

git checkout stage
git merge feature/new-feature

The stage branch is then used for final QA, user acceptance testing (UAT), or any other types of pre-production checks. If any issues arise, they can be fixed here before moving to production.

4. Releasing to Production

Once the feature passes all necessary tests and is deemed stable, it’s time to promote it to the production branch.

git checkout master
git merge stage

This ensures that only stable, fully tested features reach the production environment.

5. Syncing the Branches

To prevent branch drift, where changes in one branch don’t propagate to others, it’s essential to sync dev with stage after releasing to production.

git checkout dev
git merge stage

This step ensures that your dev environment is always aligned with the most recent stable code, preventing conflicts or issues when future features are developed.

Summary of Workflow

The following diagram summarizes the entire branching workflow:

• Feature branches are created from stage.
• Feature branches are first merged into dev for early testing and API consumption.
• Once tested, feature branches are merged into stage for final testing.
• After passing testing, stage is merged into production.
• Finally, stage is synced back to dev to maintain consistency.

Handling Hotfixes

In case of urgent hotfixes, you’ll need a special branch created directly from production. After the hotfix is applied, it should be merged into both stage and dev branches to keep all environments consistent.

git checkout master
git checkout -b hotfix/fix-urgent-bug
# Apply the fix
git checkout master
git merge hotfix/fix-urgent-bug
git checkout stage
git merge master
git checkout dev
git merge stage

Conclusion

This branching strategy ensures that only fully tested, stable features make their way into production, while also allowing for flexible, continuous development and early testing. By isolating development and staging environments, you minimize the risk of unfinished features disrupting production.

This process creates a clear flow from development to production, synchronizing the branches regularly to avoid conflicts and bugs. It’s a strategy that can scale from small teams to larger ones, keeping your codebase organized and your deployment pipeline smooth.

Are you using a different branching strategy? Share your thoughts and experiences in the comments!