Feature Branch Version Control Workflow and Avoiding Merge Hell
Working on code in isolation and incorporating peer review
Overview
Concept
Software projects in this course will follow a “feature branch” version control workflow, where changes are made in isolated branches.
Following this workflow allows team members to work independently while minimizing code code conflicts.
Repositories
The feature branch workflow requires each developer to have access to two repositories:
- a centralized remote repository accessible by everyone on the team, such as a GitHub repository
- a local clone of the remote repository
Making Changes
Pull from central repository
Before making any changes, download the latest code from the shared central repository.
With the main/master branch on the local machine checked out:
git pull
Or, if you need to be specific about where to pull from:
git pull origin main
Create a new local branch
With the latest code downloaded, create a new branch and “check it out”. The name of the branch should refer to the user story, task, or spike associated with the changes that will be made.
Example for a Task with identification number 9 belonging to a User Story with identification number 13:
git checkout -b user-story/13/task/9/implement-user-login
Example for Spike with identification number 6:
git checkout -b spike/6/install-mongo-db-locally
Update task board
In the GitHub Task Board for this Sprint, move the card for this Task or Spike to the appropriate “In Process” column.
Make changes locally
Pop open your favorite code editor and go crazy.
- A feature branch addresses an individual Task or Spike and thus should not be left unmerged with the main branch for more than a day (or ~2 days for students).
- A branch that has lived longer than 3 days is likely to lead you towards “merge hell”.
- A branch that has lived longer than 3 days is a problem the entire team must address.
Commit changes to the local branch
Add all changed files to the branch in the local repository.
git add .
git commit -m "Implementing user login task from user story #13"
Merge with latest code from central repository trunk
Download the latest code from the main branch of the shared central repository, merge it into the local feature branch, and resolve any conflicts
With the feature branch checked out:
git fetch origin
git merge origin/main
Push branch to remote repository
Once the feature branch has been merged with any recent changes to the main branch, it’s time to upload the feature branch to the shared remote repository.
For example, push a feature branch for a particular Task:
git push origin user-story/13/task/9/user-login
Issue pull request
Once the feature branch has been pushed to the remote repository, the developer must issue a Pull Request to their teammates requesting that they accept the changes into the main branch.
This Pull Request must be made using GitHub, and assigned to the teammates. This forces teammates to perform peer code review on the work before it is included in the main branch.
Update task board
In the GitHub Task Board for this Sprint, move the card for this Task or Spike to the appropriate “Awaiting Review” column.
Peer Review
Review a pull request
A second developer must review the changes in the pull request and either accept or reject them.
- If rejected, the approver must specify the reasons and ask the original developer to fix the problems.
- The original developer must fix all problems and notify the approver.
Download the feature branch for review
git checkout user-story/13/task/9/user-login
git pull
Look at the code, test it, Try it, etc…. make sure it works!
Merge changes locally
If approved, the reviewer and the original developer coordinate so that one of them merges the changes in the feature branch into the main branch.
Example of getting latest code and merging into main:
git checkout user-story/13/task/9/user-login
git pull
git checkout main
git pull
git merge user-story/13/task/9/user-login
Upload changes to remote repository
Once the changes have been merged into the local main branch, the developer who merged must upload the changes to the remote repository.
With the main branch checked out:
git push origin main
Update task board
Whoever merged the code must now move the corresponding Task into the “Done” column of the task board.
Keeping Git History Clean
Keep it simple… no rebasing
When merging a feature branch into the main/master branch, Git will create a “merge commit” that records the fact that the feature branch was merged into the main branch. This is an important part of the history and must be preserved.
-
Make sure rebasing is turned off on your local machine:
git config --global pull.rebase false -
If merging pull requests on GitHub, you must always use the “
Create a merge commit” option, never the “Rebase and merge” option, for the same reason.
Conclusions
Thank you. Bye.