June's Blog

Introduction: To standardize the team's git branch management specifications, I initially planned to write my own, but after searching online, I found many good git branch management practices.

Referring to the team's current usage, which is closer to git-flow, what is currently lacking is the release branch used for preparation before publishing from dev to master.

Finally, I chose this git branch management practice for the team: A successful Git branching model. There are many Chinese versions of gitflow practices written based on this article online. I recommend a Chinese version of Git best practices: Effective Git Branching Model.

Common git flows include git-flow, github-flow, and gitlab-flow.

Reprint an article: Understanding Gitflow, Github flow, and Gitlab flow workflows in one article

In addition, you can use the tool gitflow to easily standardize the use of git-flow branch management mode.

GitHub Flow#

Features:#

Deployment-centric development model, through simple features and rules, continuously and rapidly deploy in a secure manner.

• The master branch is always deployable.
• When starting a new task, create a new branch from the master branch, and the new branch name should be descriptive.
• Deploy immediately after merging with the master branch.

Prerequisites#

• Deployment tasks must be fully automated. It must be automated because multiple deployments may be required within a day.
• Emphasize testing
  • Automate testing
  • Write test code and pass all tests
  • Maintain test code

Git Flow#

Dutch programmer Vincent Driessen published a blog post that made a branching strategy widely known. The specific process is shown in the following figure (quoting an image from the blog).

High-resolution PDF: https://nvie.com/files/Git-branching-model.pdf

In Git Flow, the master and develop branches are crucial. They are always present throughout the entire process and should never be deleted or modified directly by developers.

To create a feature branch based on the develop branch, develop branch maintains the latest code during the development process so that developers can create their own feature branches to work on their tasks.

Specifications#

Main branch: master#

Firstly, the code repository should have one and only one main branch. All official versions provided to users are released on this main branch.

Development branch: develop#

The main branch is only used for distributing major versions, and daily development should be done on another branch. We call this branch Develop.

Temporary branches#

After use, they should be deleted so that the code repository only has the Master and Develop branches.

• Feature branches

• Created from the Develop branch for specific features. After development is completed, they should be merged back into the Develop branch.

• Release branches

• Created from the Develop branch before the official release (i.e., before merging into the Master branch). A pre-release version may be needed for testing.

  Release branches are created from the Develop branch and must be merged into both the Develop and Master branches after the release is complete. They can be named using the format release-*.

• Bugfix branches

• Created from the Master branch. After bug fixing is complete, they should be merged back into both the Master and Develop branches. They can be named using the format fixbug-*.

Simple Example of Git-flow#

For detailed usage, refer to: https://jeffkreeftmeijer.com/git-flow/

Install git-flow on Mac using Homebrew:

brew install git-flow

Initialize the project: git flow init#

Working on a feature branch: git flow feature start xxxx#

• Create a feature branch from the develop branch.
• Implement the desired feature in the feature branch.
• Send a pull request to the develop branch via GitHub.
• After approval by other developers, merge the pull request to the develop branch.

After completing the feature development: git flow feature finish xxxx

The Develop branch is protected, so it is recommended to push the feature branch to remote first and then submit a pull request to merge it into the dev branch.

To keep the original branch: git flow feature finish -k my-feature

Reference: https://github.com/nvie/gitflow/wiki/Command-Line-Arguments

Submit a pull request on GitLab or PaaS.

!!!! Important: Update the local develop branch

After the pull request we sent is merged with the develop branch on GitHub, to reflect it in the local develop branch, we need to perform the following steps:

• Switch to the develop branch.
• Execute git pull (fetch & merge).

Whenever you need to create a feature branch from the develop branch, remember to perform the above steps to ensure that the develop branch is up to date.

Preparing for release#

Create a release branch. In this branch, we only handle commits related to preparation before release, such as adding metadata for version number changes. If bugs are discovered during testing after the software is deployed to the staging environment, related fixes should also be committed to this branch.

Note: This branch must not contain major fixes such as requirement changes or feature changes. The number of commits during this stage should be kept to a minimum.

When all fixes are completed, we finish this branch.

Common Issues and Solutions#

Merge conflicts in feature branches#

Issue: When completing a feature branch and attempting to merge it into the develop branch, merge conflicts may occur.

Solution:

• Ensure that the latest changes in the develop branch have been pulled locally before merging.
• Use git merge --no-ff <feature-branch> to perform the merge, which preserves the merge operation in the commit history.
• Resolve conflicts manually, use git add <conflicted-file> to add the resolved files, and then use git commit to commit the merge.

Difficulty managing multiple feature branches#

Issue: Over time, a project may accumulate a large number of feature branches.

Solution:

• Regularly clean up feature branches that are no longer needed.
• Use git branch -d <feature-branch> to delete local branches and git push --delete origin <feature-branch> to delete remote branches.
• Train team members and emphasize the importance of completing or abandoning feature branches.

Issues with merging release branches#

Issue: When preparing for a release, the release branch created from the develop branch may encounter issues when merging into the master and develop branches.

Solution:

• Ensure that the develop branch is stable before creating the release branch.
• Ensure that all tests pass before merging into master.
• When using the git flow release finish command, carefully review the automatically generated merge requests.

Managing emergency bug fix branches#

Issue: Emergency bug fixes need to be quickly merged into the master and develop branches.

Solution:

• Use git flow hotfix start <hotfix> to quickly create a hotfix branch.
• After completing the fix, use git flow hotfix finish <hotfix> to ensure that it is merged into both master and develop.
• Update the version number and related documents after merging.

Collaboration conflicts between multiple teams#

Issue: In large projects, multiple teams may be working on different feature branches at the same time.

Solution:

• Use pull requests for code review and merging.
• Hold regular team meetings to discuss progress and potential merge conflicts.
• Use tags and milestones to track the progress of each team.