Introduction

When creating a topic which fixes an issue in a release branch that also applies to the master branch, there are numerous cases that may occur. In general, topics should be based on the oldest branch the issue affects and when creating a merge request, target the newest branch that is affected.

In merge requests which target multiple branches, this is indicated using a Backport trailer in its description. Trailers belong at the end of the description. The format for the trailer is:

Backport: TARGET_BRANCH[:COMMIT]

The target branch is required and the commit section is optional. If the commit is missing, the head of the merge request topic is assumed. The commit may also contain HEAD to refer to this commit to use ancestor modifiers to walk back the history of the topic for backporting. Each case shows what would be the correct Backport trailer for the commit graph shown.

Backporting to multiple branches is possible using multiple Backport trailers:

Backport: TARGET_BRANCH_1[:COMMIT_1]
Backport: TARGET_BRANCH_2[:COMMIT_2]

Example

The common case for backporting is where you want a topic to apply to both the master and release branches. In this case in order to create the topic, you would branch off of the release branch and change the code:

git checkout -b my-topic release
# git (add|commit)
git push myfork my-topic

When opening the merge request, you would set the Target branch to master. In addition, the end of the merge request description should include a Backport: release trailer. When merged, the topic will be merged into both the release and master branch.

Cases

Fixing only master

This is the common case. Topics should branch from master and be merged into master.

gitGraph
  commit
  branch topic
  checkout topic
  commit
  commit
  checkout main
  commit
  merge topic

Fixing only release

When an issue only exists in release, it is very similar to the master case. This happens when an issue is found in a feature that master has removed.

gitGraph
  branch release
  commit
  branch topic
  checkout topic
  commit
  commit
  checkout release
  commit
  merge topic

Fixing both without conflicts

When an issue that occurs on master and release can be fixed with the same patch, the Git topic branch should be based off of release and the merge request should specify its target branch as master. When merged, it will appear on both branches.

gitGraph
  branch release
  commit
  commit
  branch topic
  checkout main
  commit
  commit
  checkout topic
  commit
  commit
  checkout release
  merge topic
  checkout main
  merge topic

Backport: release

Fixing both with conflicts

When an issue that occurs on master and release cannot be fixed with a single patch due to conflicts or other, unrelated changes, there are three subcases.

master requires extra changes

The first is where the fix to release is a subset of the fix necessary for master. Here, the topic should be started off of release and fixed for release. Then, a second topic should be created off of master The first commit here should merge the fixes to release and be followed up with changes which fix the code which only occurs on master.

gitGraph
  branch release
  commit
  commit
  branch topic-common
  checkout main
  commit
  commit
  checkout topic-common
  commit
  commit
  branch topic
  checkout topic
  commit
  commit
  checkout release
  merge topic-common
  checkout main
  merge topic

Backport: release:HEAD~^2

release and master require completely different changes

The other case is where two disjoint fixes need to be made on release and master. This normally arises when the release branch follows a release branch of a submodule. This case sees two branches merged together using the -s ours strategy to tie the history together, but ignore the changes.

gitGraph
  branch release
  commit
  commit
  branch topic-common order: 2
  checkout main
  commit
  commit
  branch topic order: 1
  checkout topic-common
  commit
  commit
  checkout topic
  commit
  commit
  merge topic-common type: HIGHLIGHT
  checkout release
  merge topic-common
  checkout main
  merge topic

Backport: release:HEAD^2

release and master require some different changes

The last case is a combination of the last two. This case sees two branches merged together twice, once normally and the second using the -s ours strategy to tie the history together, but ignore the changes.

gitGraph
  branch release
  commit
  commit
  branch topic-for-release order: 2
  checkout main
  commit
  commit
  branch topic order: 1
  checkout topic-for-release
  commit
  commit
  checkout topic
  merge topic-for-release
  commit
  commit
  checkout topic-for-release
  commit
  commit
  checkout topic
  merge topic-for-release type: HIGHLIGHT
  checkout release
  merge topic-for-release
  checkout main
  merge topic

Backport: release:HEAD^2

Backporting an already-integrated fix

If an issue has been fixed on master and the change should have been applied to release, the original topic should be used if possible. This is not always possible because the fix may have been based on master after release was branched.

Topic is old enough

If an issue has been fixed on master and should have been applied to release, the original topic should be used if possible. If on its own, it is not based on master that is too new to the release branch, the original topic should be used to create a new merge request which targets the release branch.

gitGraph
  commit
  commit
  branch release
  commit
  commit
  branch topic
  commit
  commit
  checkout main
  commit
  commit
  checkout release
  merge topic
  checkout main
  merge release type: HIGHLIGHT
  commit
  commit
  merge topic

Topic is branched after release

If the fix for master was branched after release, the commits need to be made into a new topic based on release using git cherry-pick -x. The -x flag adds the original commit hash to the commit message. This helps to link the fixes together. The merge request for the release branch should reference the original merge request for master as well.

gitGraph
  commit
  commit
  branch release order: 2
  commit
  commit
  checkout main
  commit
  commit
  branch topic order: 1
  commit
  commit
  checkout main
  merge topic
  checkout release
  branch topic-backport order: 3
  commit
  commit
  checkout release
  merge topic-backport

Forwardporting an already-integrated fix

When a issue has been fixed in release and is later found to be necessary in master as well, simply merging the original topic may not be possible. This is because the master branch usually keeps updates of the release branch merged in automatically using the -s ours strategy. This is to ensure that the release branch commits are always reachable from master. In this case, the commits must again be cherry-picked into a new topic because a simple merge will not do anything because git considers the topic "already merged" and will not apply.

gitGraph
  commit
  commit
  branch release order: 2
  commit
  commit
  checkout main
  commit
  commit
  branch topic-reapply order: 1
  commit
  commit
  checkout main
  merge topic-reapply
  checkout release
  branch topic order: 3
  commit
  commit
  checkout release
  merge topic