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!