How to use a Git workflow for versioning

Why implement a Git workflow?

A Git workflow helps teams develop and deliver isolated features or product increments until they’re completed, documented, tested and approved. Only then are changes incorporated into the main branch and considered deliverable.

Feature isolation makes it easy for multiple developers to work on a particular feature without disturbing the main codebase.

The main branch will never contain incomplete features or broken code. Therefore, anything in the main branch is always deliverable.

Principles and rules

• Anything in the main branch is DELIVERABLE.
• Create feature branches from the main branch when working on something new.
• No direct commits on the main branch.
• Commit and push your work regularly on the branch you're working on.
• Open a Draft PR whenever you need help or feedback.
• Open a PR when your work is complete.
• Releases are based on tags.
• Fix bugs in the main branch first and releases branches second.
• Commit messages should reflect intent.

How to develop new features

When adding new features to an existing product, we suggest the following workflow:

• When starting to work on a new feature always checkout from main: that will be the source of truth.
• Create new branch called feature/feature-number-feature-name.
• Create a new branch from feature/feature-number-feature-name to develop PBI named dev/pbi-number-feature-name.
• Once PBI development is completed, open a PR on feature/feature-number-feature-name branch.
• Merge the feature branch into the qa/ branch that will be used to deploy and test the feature.
• Once the feature has been tested, make the PR merge feature/feature-number-feature-name into main.
• Once your branch has been merged into main, delete the feature branch.

How to do a hotfix:

When a bug or error occurs and a hotfix can be done by creating a new hotfix branch. Here’s our process:

• Checkout and pull from the latest commit on main.
• Create a new branch hotfix/bug-number-name-of-bug (or hotfix/name-of-bug if not related to a bug PBI).
• On hotfix branches, only bugs will be solved.
• Once completed and validated, create a PR to main (prod first in this case), once PR is approved cherry-pick to release/*. main branch should be tagged with an updated version number.

Branch Naming Conventions

Git branch names help to organize ongoing work to ensure a smooth software delivery. There are two main categories for branch names: permanent and temporary.

Permanent branches

main

The main branch is for all stable and tested features. It is associated with nightly CI/CD and protected by branch policies. Any changes to main go through PR only.

Tag all releases in the main branch with Git tags.

Temporary branches

feature/*

When working on a specific feature, use feature/*. Delete after merging on main. Changes from feature branches to the main only go through PR. However, when working on small features, direct commits are allowed.

qa

The qa branch is a write-only branch used for testing new features. No developments are done in this branch.

hotfix/*

Used to fix a bug found on main or release/*

release/*

Create a release branch when doing a hotfix on an LTS version. The release branch is deleted when a version is no longer maintained. No feature enhancements or chores are allowed.

How to resolve conflicts when creating a PR to main or release/*

When creating PR from feature/feature-number-feature-name to main you could have to resolve conflicts.

To do this, you simply merge the latest version of main into your current branch, resolve the conflicts, and push a new commit to origin:

git checkout feature/feature-number-feature-name

git fetch origin && git pull origin main <resolve merge conflicts + commit changes>

How to merge a new feature not yet available inside your branch

For example, let’s say someone developed feature/1234-countdown and made a PR on main, which is still waiting for approval.

If you need some of the files of that branch, you would:

1. Checkout on main and create a new branch feature/5678-countdown-for-events
2. Checkout on new feature/5678-countdown-for-events
3. Then you will (choose 1 or 2):
   1. Fetch and merge inside your current branch all the commits
      1. (this will pollute the branch history and won't be totally independent)
      2. git pull origin feature/1234-countdown
   2. Perform a cherry-pick to merge single commit, because maybe you're interested only in one single commit
      1. (git history will change so, be careful)
      2. git cherry-pick <commit-hash>

How cherry-pick a range of commits (tip for bugfixes and updates)

Sometimes we need a range of commits to cherry-pick inside our current branch (imagine a hotfix-branch you want to pull inside your current branch).

We can check the hashes and then type Git cherry-pick ebe6942^..905e279

The first hash in the range is the oldest commit, and the last hash is the newest commit.

This syntax ^ will include the first commit object; otherwise, it won't be included.

Fixing mistakes

Sometimes mistakes can happen. For example, if you accidentally merged qa into your current feature/feature-number-feature-name and pushed it to remote (worst scenario). Or maybe you need to undo some bad commits (e.g. pushed to origin) and delete them from branch history to keep the branch history clean. To fix such mistakes, we recommend the following workflow:

1. Checkout on your branch: git checkout feature/feature-number-feature-name
2. Perform a log to see the list of branch history with: git log --graph –oneline
3. Reset the brand HEAD to a specific commit (the one before the merge) with: git reset --hard <commit-hash>
4. Push the current HEAD (positioned to the hash specified before) to the origin, in order to override the history, with: git push origin HEAD --force

Doing this ASAP will avoid the pull of the polluted branch by other team members.

Rename last commit message

If you pushed a commit with a wrong/bad message, you could perform these activities to rename your last commit and re-push it to the origin:

git commit --amend -m "New commit message"

git push origin HEAD –force

Summary

A Git workflow can help teams work on the correct versions of code without affecting the main codebase before a new feature or increment is ready. We hope that the insight into our workflow and naming conventions helps you implement your own Git workflow.