inanzzz | Working with gitflow release branches

Release branches contain production ready new features and bug fixes that come from stable develop branch. In most cases, master branch is always behind develop branch because development goes on develop branch. After finishing release branches, they get merged back into develop and master branches so as a result both of these branches will match each other eventually. We will see that below.

May branch off from develop.

Must merge back into develop and master.

Branch naming convention is release/x-x-x. The x[major release]-x[release]-x[hot-fix] signs represent the release tag. e.g. If the current tag in your repository is "0.1.4" then your next tag will be "0.2.0" for release branch. The one in the middle gets bumped up by "1" and the last one gets reset to "0" so our new release branch name should be release/0.2.0. Next one will be release/0.3.0.

When working with release branches, you should open up a "pull request" in GitHub so that your team members can see what you're preparing to release. This is considered as the best practise! Also pay attention to "Summary of actions" notes in code.

Preparation

These steps are compulsory before start working on a new release branch because our local branch might be behind remote copy.

Step 1

Make sure we're on develop branch.

$ git branch
* develop
  master

Step 2

Fetch all remote updates.

$ git remote update
Fetching origin

Step 3

Update local develop branch so it is up-to-date with remote copy.

$ git pull origin develop
From github.com:inanzzz/manual
 * branch            develop    -> FETCH_HEAD
Already up-to-date.

Step 4

Checkout into master branch and update it so it is up-to-date with remote copy.

$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

$ git pull origin master
From github.com:inanzzz/gitflow
 * branch            master     -> FETCH_HEAD
Already up-to-date.

Create release branch

Step 1

Check the current git status.

$ git branch -avv
* develop                24683c1 [origin/develop] Feature hello-world commit
  master                 c9b8a72 [origin/master] Very first commit
  remotes/origin/develop 24683c1 Feature hello-world commit
  remotes/origin/master  c9b8a72 Very first commit

Step 2

Start release branch.

$ git flow release start 0.1.0
Switched to a new branch 'release/0.1.0'

Summary of actions:
- A new branch 'release/0.1.0' was created, based on 'develop'
- You are now on branch 'release/0.1.0'

Follow-up actions:
- Bump the version number now!
- Start committing last-minute fixes in preparing your release
- When done, run:

     git flow release finish '0.1.0'

As you can see below, release branch is branched off from local develop branch.

$ git branch -avv
  develop                24683c1 [origin/develop] Feature hello-world commit
  master                 c9b8a72 [origin/master] Very first commit
* release/0.1.0          24683c1 Feature hello-world commit
  remotes/origin/develop 24683c1 Feature hello-world commit
  remotes/origin/master  c9b8a72 Very first commit

Step 3

Publish release branch.

$ git flow release publish 0.1.0
Total 0 (delta 0), reused 0 (delta 0)
To git@github.com:inanzzz/gitflow.git
 * [new branch]      release/0.1.0 -> release/0.1.0
Branch release/0.1.0 set up to track remote branch release/0.1.0 from origin.
Already on 'release/0.1.0'
Your branch is up-to-date with 'origin/release/0.1.0'.

Summary of actions:
- The remote branch 'release/0.1.0' was created or updated
- The local branch 'release/0.1.0' was configured to track the remote branch
- You are now on branch 'release/0.1.0'

Step 4

If you go to GitHub, unlike feature branches, there won't be a notification bar waiting for you to open a new "pull request" for the release branch you've just published so you need to do it manually instead. To open a "pull request" for the release branch, hit "New pull request" button, compare master (base dropdown) branch to release/0.1.0 (compare dropdown) branch, write a subject and a description for it. This will open a "pull request" so that it can be reviewed by other team members. If what commits you're preparing to release are fine for the rest of the team members then there is nothing to worry about. This process just shows everyone what will be released. Do not use "Merge pull request" button.

As you can see below, we have release branch published in GitHub.

$ git branch -avv
  develop                      24683c1 [origin/develop] Feature hello-world commit
  master                       c9b8a72 [origin/master] Very first commit
* release/0.1.0                24683c1 [origin/release/0.1.0] Feature hello-world commit
  remotes/origin/develop       24683c1 Feature hello-world commit
  remotes/origin/master        c9b8a72 Very first commit
  remotes/origin/release/0.1.0 24683c1 Feature hello-world commit

Step 5

Finish release branch.

$ git flow release finish 0.1.0
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
Merge made by the 'recursive' strategy.
 one.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 one.txt
Switched to branch 'develop'
Your branch is up-to-date with 'origin/develop'.
Already up-to-date!
Merge made by the 'recursive' strategy.
To git@github.com:inanzzz/gitflow.git
 - [deleted]         release/0.1.0
Deleted branch release/0.1.0 (was 24683c1).

Summary of actions:
- Release branch 'release/0.1.0' has been merged into 'master'
- The release was tagged '0.1.0'
- Release tag '0.1.0' has been back-merged into 'develop'
- Release branch 'release/0.1.0' has been locally deleted; it has been remotely deleted from 'origin'
- You are now on branch 'develop'

As you see below, all of the "Summary of actions" steps above done however all took place in local repository so we need to reflect all to remote repository as well.

$ git branch -avv
* develop                8f11c42 [origin/develop: ahead 2] I merged release 0.1.0
  master                 8aa2add [origin/master: ahead 2] I merged release 0.1.0
  remotes/origin/develop 24683c1 Feature hello-world commit
  remotes/origin/master  c9b8a72 Very first commit

Step 6

Push local develop branch to remote repository.

$ git push origin develop
Counting objects: 2, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 355 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)
To git@github.com:inanzzz/gitflow.git
   24683c1..8f11c42  develop -> develop

Step 7

Push local master branch to remote repository.

$ git push origin master
Total 0 (delta 0), reused 0 (delta 0)
To git@github.com:inanzzz/gitflow.git
   c9b8a72..8aa2add  master -> master

Step 8

Verify that the tag has been created.

$ git tag
0.1.0

Step 9

Push the tags to remote repository. If you go to GitHub, you'll see the tag under "Release" tab.

$ git push --tags
Counting objects: 1, done.
Writing objects: 100% (1/1), 181 bytes | 0 bytes/s, done.
Total 1 (delta 0), reused 0 (delta 0)
To git@github.com:inanzzz/gitflow.git
 * [new tag]         0.1.0 -> 0.1.0

Step 10

Check git status. As you can see below, local and remote branches match each other.

$ git branch -avv
* develop                8f11c42 [origin/develop] I merged release 0.1.0
  master                 8aa2add [origin/master] I merged release 0.1.0
  remotes/origin/develop 8f11c42 I merged release 0.1.0
  remotes/origin/master  8aa2add I merged release 0.1.0

Step 11

If you go to GitHub, you'll should see cases below happened.

The master and develop branches are even.

The release tag "0.1.0" is there.

The release branch itself is deleted.

The release "pull request" that we've opened is deleted.

Deployment

In the case deployment, you should checkout into tag number and deploy it.

$ git remote update
$ git checkout 0.1.0
$ git pull origin 0.1.0
$ cap production deploy

Overview

In short terms, this is what we did above.

# 1. Checked out into develop branch
git checkout develop

# 2. Fetched all remote updates
git remote update

# 3. Update local develop branch with remote copy
git pull origin develop

# 4. Checked out into master branch
git checkout master

# 5. Update local master branch with remote copy
git pull origin master

# 6. Checked out into develop branch
git checkout develop

# 7. Start release branch
git flow release start 0.1.0

# 8. Publish release branch
git flow release publish 0.1.0

# 9. Opened a "pull request" in GitHub for team to verify the release

# 10. Finish release branch
git flow release finish 0.1.0

# 11. Pushed develop branch to remote repository
git push origin develop

# 12. Pushed master branch to remote repository
git push origin master

# 13. Pushed the tags to remote repository
git push origin --tags