MS Docs

Branching strategy

About Branching

The branching strategy iOS team use isn't complex. It simply requires you and your team to stick to a few rules.

  • All project repositories located in Mind Studios GitLab repoopen in new window should contains all main branches according to this document.

  • Main branches should be named exactly the same way as described in this document.

  • Any changes can not be pushed straight forward to any of main branches, you should create merge request for that. It's very important to be sure that main branches have been protected!

Types of branches

We defines two types of branches, the main branches and supporting branches. The main branches are master and develop. They have an infinite lifetime. Supporting branches have a limited lifetime. They are created with a specific goal and destroyed when they are no longer needed.

Feature Development

In order to implement the function without running into problems, we create a feature branch. A feature branch starts its life on develop and, once the feature is ready to be released, the changes are merged into develop. It's safe to destroy the feature branch after merging it into develop.

Adopting this simple strategy has several benefits. Feature development is isolated and doesn't affect develop, making parallel development possible and straightforward. Scrapping the feature a few weeks into development isn't a problem and doesn't affect develop or the work of other team members. By adding a little bit of complexity, you gain the flexibility you need.

You can also use this branching strategy for bug fixes and it works well in a team if you create a pull request for every feature or bug fix that goes into the next release. Code reviews are focused and it's easy to make changes or collaborate with team members without touching develop. Remember that you only merge a feature or bug fix branch into develop when the feature or bug fix is complete and tested.

We prefix feature branches with feature/ and bug fix branches with bug/. There's a reason for using a forward slash instead of a dash. The most popular Git clients treat this format as a path. They create a folder named feature and bug in which feature and bug fix branches are located. This is convenient if you're frequently creating supporting branches. We also mention a Jira issue ID in the branch name for automating work with GitLab in Jiraopen in new window.

  • Feature branch name should be: feature/ID_NAME. Where ID - Jira feature id, NAME - name of the feature.

  • Bug branch name should be: bug/ID_NAME. Where ID - Jira bug id, NAME - name of bug

Release Management

The power of this branching strategy becomes clear once you start to use supporting branches for release management. We add another bit of complexity for more flexibility. Remember that develop reflects the current state of development. When a feature or bug fix is completed, it is merged into develop and scheduled for the next release. We use a similar approach for managing releases. We create a release branch from develop when its current state is considered ready for release.

Creating a release branch follows the pattern of feature and bug fix branches. A release branch starts its life on develop. The name of the release branch is the version of the release prefixed with release/. The release branch serves three goals. First, the release is prepared. This includes updating the version number. Second, the release is tested and bug fixes are applied to the release branch. Third, by creating a release branch develop isn't blocked. It can still receive changes.

It's important to emphasize that no major changes should be introduced into the release branch. Only bug fixes that block the release should be included.

The moment you or your team are confident about the stability of the upcoming release, a release candidate is created from the release branch and submitted to App Store Connect or deployed to production, depending on the type of software you're developing.

After releasing or deploying to production, the release branch is merged into master and develop. Merging the release branch back into develop is sometimes overlooked. It's essential that any changes that were introduced into the release branch, such as bug fixes, make their way back into develop. After merging the release branch into master you tag master with the version of the release.

Creating a Release Branch

When should you create a release branch? What's included in the next release is defined beforehand. When every feature and bug fix has been merged into develop, a release branch is created and a release candidate is scheduled for release.

Hotfixes

There's another kind of supporting branch that needs mentioning, hotfix branches. As the name implies, a hotfix branch is used to fix a critical problem in production. Consider the following example. You create a release branch from develop. From the moment the release branch is created, it's fine to add new commits to develop because the release branch isn't affected by what's happening on develop. A few days later, you release the build to production and the release branch is merged into master and develop.

A team member has completed its feature and merges it into develop. A few hours later, another team member spots a critical problem in production. The issue needs to be patched as soon as possible. What do you do? You apply a hotfix. How do you create a hotfix? Which branch should the hotfix branch originate from?

It may make sense to follow the same branching strategy I outlined for a regular release. That isn't a good idea, though. A hotfix should only include the changes that are required to fix the critical problem. Why is that? A hotfix needs to be applied as soon as possible and you usually don't have the time to test a hotfix as thoroughly as a regular release.

You can't use develop as the originating branch of the hotfix branch because it's possible that develop has changes that shouldn't be included in the hotfix. The answer is simple. You create a hotfix branch from master, apply the solution, and release the hotfix. After releasing the hotfix, the hotfix branch is merged into master and develop, like a regular release. If there's an active release branch present the moment the hotfix branch is created, then the hotfix branch is merged into master and the release branch. The changes of the hotfix automatically make their way into develop when the active release branch is released.

Hotfixes should only be applied in emergencies. If the problem in production isn't critical, then it may be better to include the bug fix in the next release.

Tagging

master is tagged every time a release is pushed to production. We tag master with the version of the release.