What is a branching strategy?

Branching strategy is the strategy that software development teams adopt when writing, merging and deploying code when using a version control system. It helps keeping repositories organized and avoiding merge issues. Following a branching strategy enables teams to work in parallel to achieve faster releases and fewer conflicts by defining a clear process when making changes to source control.

Note

OSB relies on Git, which is the de facto standard version control system in software development industry.

Principles

Use feature branches for new features and bug fixes

Feature branches isolate work in progress from completed work. Git branches are inexpensive - even small changes should have their own feature branch. Creating branches makes reviewing simple.

gitGraph
   commit
   commit
   branch feature
   checkout feature
   commit
   commit
   checkout main
   merge feature
   commit
   commit

Follow naming convention

When creating a new branch, follow below naming convention rules:

  • bug/<work_item_number>_description
  • feature/<work_item_number>_description
  • hotfix/<work_item_number>_description

Use feature flags for long-running implementations

Feature flags allow modifying system behavior without changing code. Implementing a new feature might take several weeks, thereby not fitting into a single sprint or a release. Feature flags help with avoiding merge issues with long-lived branches. For more information on how to manage feature flags with Azure, consult Microsoft learn. Feature flags

Review and merge between branches with pull requests

Code review takes place with every pull request. Implementing code review process is critical for improving code quality. Only pull requests that pass code review process can be merged.

Best practices to follow:

  • At least one reviewer has to be assigned to each pull request.
  • No one can approve their own pull requests. This must be enforced by branch policy.
  • Provide enough detail in the description to bring reviewers up to speed with changes.
  • Pull requests must be linked to at least one work item.
  • Implement CI builds to ensure that the code is not broken and passes all unit tests. This must be enforced by branch policy.
  • Direct pushes are allowed only to feature branches. Other branches have to be protected by branch policy.
  • All comments have to be resolved. This principle has to be forced by branch policy.
  • Limit allowed merge types by branch policy. Use Squash merge or Rebase with merge commit to keep clean target branch's history.
  • Improve pull request descriptions using OSB's PR template. Additional templates can be defined on project level to support further needs. Visit Microsoft learn for more information about pull request templates.

Release management

Use environment branches and continuous deployment to promote releases to deployment target environments.

gitGraph
   commit
   branch test
   checkout test
   commit
   branch dev
   checkout dev
   commit
   branch feature
   checkout feature
   commit
   commit
   checkout dev
   merge feature
   checkout test
   merge dev
   checkout main
   merge test

Hotfix

To deliver a hotfix into production, create a hotfix branch from the main. When the hotfix is completed and tested, create a pull request to merge it back to main. Make sure that the hotfix is ported to other environment branches.

gitGraph
    commit
    branch test
    commit
    branch dev
    commit
    commit
    checkout main
    commit
    branch hotfix
    checkout hotfix
    commit
    checkout main
    merge hotfix
    checkout test
    merge main
    checkout dev
    merge test