Why “Branch is Out-of-Date” is Important

Exploring through a simple example the importance of a GitHub warning.

Image for post
Image for post

note: While this article is written with Git and GitHub in mind, the concepts apply to any source-control-management system.

I recently ran into a situation where I was asked to help QA (and merge) several pull requests at the end of the day and came across a screen like this.

Image for post
Image for post

note: If you are wondering, in this and subsequent images you will notice two status checks; this is because I accidentally activated this example repository with travis-ci.com and travis-com.org.

First, one will only get a screen like this if the repository has the branch protection feature enabled, enable the up-to-date requirement, and are using a continuous integration solution; say Travis CI.

Image for post
Image for post

This warning, this branch is out-of-date with the base branch, appeared on the second and subsequent pull requests that I reviewed; I successfully merged the first one. Out of the abundance of caution, I decided to give the work back to the QA team for the next day.

Got to thinking about this later that night.

My first thought was that the developers of the second and subsequent branches mistakenly did not merge in the latest version of master before creating their pull request (bad-bad developer 😄). However, through a bit of investigation, I determined that this was not the case.

In thinking about this a bit more, I realized that the first pull request I merged caused the subsequent ones to be out-of-date; my QA actions caused the warnings

So if I just had opened up each of the pull requests before merging the first one, they all would have looked fine (passing tests and all) with no warnings. Then I could have merged all them without any warnings.

Turns out that I would have been wrong to do this. Let us look at a simple example illustrating the importance of the, this branch is out-of-date with the base branch, warning.

Master

Image for post
Image for post

We start with a successfully tested master branch consisting of three application files and one test.

src / a.js

src / b.js

src / value.js

src / value.test.js

Pull Requests

Image for post
Image for post

We create two branches, flip-a and flip-b; each flipping their respective module’s export to false. We then create merge requests for each of them.

Image for post
Image for post
Image for post
Image for post

Observations:

  • It is important to understand that tests on pull requests are performed on the current state of master with the changes from the pull request applied; anticipating the future merged state of master
  • Observe that the each of the branches and pull request are successfully tested; with each individual pull request applied the export from value.js is true because of the or operator.

Merge flip-a

Image for post
Image for post

With a successful test we can safely merge the PR from the flip-a branch.

Image for post
Image for post

As anticipated, the subsequent test on master is successful.

Image for post
Image for post

Merge flip-b

Image for post
Image for post

While the flip-b PR had a successful test, it anticipated a different future state of master (with only the changes from the flip-b branch applied). We can observe there is a hint of a problem as it is reporting; This branch is out-of-date with the base branch.

Image for post
Image for post

Merge flip-b Anyway

Image for post
Image for post

One approach is to think that because I, doing the QA and merging flip-a, actually caused the warning, it is fine to merge the pull request (ignoring the red warning).

I would have been wrong.

Image for post
Image for post

Update flip-b

Image for post
Image for post

The safer approach is update the branch, anticipating the true future state of master and thus re-running the test; in this case the PR’s test fails and we should not merge to master.

Image for post
Image for post

Wrap Up

Bottom line, by understanding that one can have multiple successfully tested pull requests and have their combined result fail, we can better understand the importance of the, This branch is out-of-date with the base branch, warning. And in particular, it is best to heed the warning and merging the latest changes from master into the branches before continuing.

Written by

Broad infrastructure, development, and soft-skill background

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store