Gamasutra is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Gamasutra: The Art & Business of Making Gamesspacer
Branching For The Win: How Black Rock Uses Code Branches
View All     RSS
May 22, 2019
arrowPress Releases
May 22, 2019
Games Press
View All     RSS

If you enjoy reading this site, you might also want to check out these UBM Tech sites:


Branching For The Win: How Black Rock Uses Code Branches

July 20, 2010 Article Start Previous Page 2 of 3 Next

Best Practice

Figure 2. A Branch Per-Team.

When we started, we picked a simple arrangement of branches. Each team in the studio got a branch, and if the teams were big enough they had child branches for each of their sub-teams. Actually this works pretty well. Each team working on a branch was pretty tight knit and focused, and that gives most of the win.

Each team can be using the same core libraries for pretty different projects. Over the last two years, we've had teams working on Pure, on Split/Second, and the technology itself.

To keep us honest, there are a lot of tests we run on servers; from unit tests to module tests to game tests, and there is a feedback system so that you can keep track of the branches of interest.

Unfortunately, some of the full game tests are slow (hours in total) and this influences our approach to branching. Sometimes the tests get broken in a team's branch. That's fine; we fix it.

If you're trying to merge at that time it's pretty inconvenient. What broke the build: the merge or your development changes? We use an "Airlock" system of two branches to deal with this. The parent branch has a merge branch hanging off it and the team's development branch hangs off that.

Figure 3. "Airlock" pairs of development and merge branches.

With this arrangement, we only push transactions into the merge branch which have passed all our tests. Any test failures that we see in the merge branch are the result of the merging. This merge branch is always stable and we use it to track the parent branch, incrementally merging changes both up and down.

As teams get more experienced working with branches we've seen a tendency for teams to start setting up new branches for individual features. In many ways, this is the perfect way of working: collaborate with just the people who are working directly with you at any given moment.

You don't even have to set up the branch before working on feature X. Just start working in a working directory under your team's branch. If and when you start collaborating with other people on X, you can create a new branch under your team's branch, move your working directory to it and have your collaborators do the same.

Figure 4. Feature Branches.

In practice this flexibility is fantastic, although it may highlight other areas of infrastructure which don't offer the same flexibility. For us, setting up tests for a new branch takes longer than setting up the branch, which is something we'll be addressing in the future.

For Split/Second we've seen the hierarchy of branches adapt to the current state of the project. In Accurev and many DVCSes, branches and working directories can be easily moved so that they have a new parent.

Split/Second started with a small team, working in a single mainline branch. Once the project had ramped up into full production, there were nine branches in active development. In practice, that seemed to be too many branches to promote to a single stream, due to the amount of change and breakage seen in the mainline. These development branches were grouped under two merge branches (Merge1 and Merge2) sitting under the mainline.

Figure 5. Development with Merge Branches.

When the project was feature complete and being finally bug fixed and tweaked, Merge1 and Merge2 were removed and all branches were pushed direct into the mainline. There was simply much less merging to be done. A more direct connection to the mainline was desirable.

Figure 6. Bug fixing direct to Development Branch.

For long-running branches, from which changes will be pushed into the mainline, there's a question of when to merge. A merge isn't required until you wish to push into the mainline, so, perhaps, that's the only time to merge conflicts between the branches.

In practice, this is somewhat of a gamble. Effectively this is putting an unknown amount of merging work right at the point of feature delivery. Practically we've found it better to keep an eye on conflicts (your VCS should be able to show this to you without you actually merging) and merge regularly.

We've found that merging conflicts as soon as there is confidence that both branches involved are stable is a win. Regular merging allows more regular pushes of work into the mainline, which, in turn allows those pushes to be smaller and easier to merge. This is the same principle as Continuous Integration.

From this, it's clear that there are social issues to manage across teams in different branches of the same repository. Having one team merging and pushing incrementally is of no benefit if another team works on global architectural changes for a few months and then pushes them into the mainline.

Within a single game there's often strong technical and project management organization which ensures that information flows to where it needs to go. However, across multiple games and the technology group, there may not be the organizational and social infrastructure to make code sharing work across branches.

Games are independent entities and generally, rightly, managed as such. If several games are using a given library there may be a diverging vision for that library between the teams. We handle this by making sure there is regular face to face communication between peers at all levels in the studio. For example, all the tools guys meet up once a week to catch up on current work and future plans. This way we get a small team feel for each discipline across the studio and we also minimize conflicts during merges.

Article Start Previous Page 2 of 3 Next

Related Jobs

Square Enix Co., Ltd.
Square Enix Co., Ltd. — Tokyo, Japan

Experienced Game Developer
Deep Silver Volition
Deep Silver Volition — Champaign, Illinois, United States

Technical Artist - Cinematics
Flight School
Flight School — Montreal, Quebec, Canada

Game Programmer
Dream Harvest
Dream Harvest — Brighton, England, United Kingdom

Technical Game Designer

Loading Comments

loader image