Why “Branch is Out-of-Date” is Important
Exploring through a simple example the importance of a GitHub warning.
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.
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.
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
We start with a successfully tested master branch consisting of three application files and one test.
src / a.js
module.exports = true;src / b.js
module.exports = true;src / value.js
const a = require('./a');
const b = require('./b');module.exports = a || b;
src / value.test.js
const value = require('./value');test('value to be true', () => {
expect(value).toBe(true);
});
Pull Requests
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.
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
With a successful test we can safely merge the PR from the flip-a branch.
As anticipated, the subsequent test on master is successful.
Merge flip-b
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.
Merge flip-b Anyway
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.
Update flip-b
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.
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.
