So now that Alpha 11 is out the door, what comes next for Team Stonehearth? Well, some housekeeping, for better or worse. If you’re really curious about the nuts and bolts of software development, read on! If not, no worries, send us a pic of something awesome you’ve built in A11, instead!

Let’s start with some basics. How do 6 people actively work on one software project without constantly stepping on each others’ code changes? Software projects like Stonehearth are very large, and consist of thousands of code files. One primitive and completely unworkable solution is for everyone to split up the work such that they touch only their designated code, and interact with others’ code only through pre-determined functions, called “APIs.” There are a lot of reasons this doesn’t work—the least of which is that no matter how carefully you slice up a project, two people will eventually both need to edit code in a file that’s important to both of them. Unless they’re sitting beside each other 24/7,  one of them will make changes that will break the other person’s code, and fistfights ensue. So if you work in software, or even on large group coding projects, you probably already know that the answer to this problem is “source control,” also called version or revision control.

Source Control for Stonehearth

All of Stonehearth’s code files are stored in a common repository on a 3rd-party site called Github. As each engineer joins the team, they install github’s souce control software, called Git, make a Github account, and use Git to ask the central repository for a copy of the code that will live on their local machine. (This process is called “pulling” in git, and other things in other kinds of source control.) The engineer makes changes to their local copy of the code, and then asks github for permission to upload their local changes to the central repository.

If no other changes have been made between the time they got the code and when they’re ready to submit their changes (called “pushing” in git), their new code is added seamlessly to the central repository. If, however, someone ELSE has made changes to those files in the interim, github will block the push and require that the engineer download the new, recently changed version of the code to their local machine. Then it will show the engineer all the lines in which their changes conflict with their teammate’s. The engineer then has to “resolve” all the changes by editing the file in such a way that both people’s changes work on their local machine. This can be tricky—it’s hard, sometimes, to guess what your friends meant to do when they were writing code, which is another reason why it’s so important to write clean, readable code. In any case, when all conflicts are resolved, and when the engineer is satisfied that everything is working as it should, git will allow the engineer to push their code changes to the central repository (unless, of course, someone ELSE has pushed changes while they were resolving the last set of conflicts).

On large teams, with lots of dependencies between people, it can take days to make a successful code change. We’re very happy Stonehearth has a very small team.

Unstable Changes, Branches

So if everyone is always working on the same code, and has to merge changes every time they themselves want to make a change, what happens when a couple people have to make a massive number of changes that will probably affect everyone else’s work? The source control solution to this is “branching”: basically, making a separate, central copy of all the code, and then working off of that copy until the feature is mostly complete. Then, the “branch” is “merged” back to the main code base, which again requires looking at each conflicting line and manually editing them so that all the features in the main branch, and on the feature branch, still work. It’s like a giant version of the individual check-in process, the benefit being that the unstable code on the branch remains isolated from the main body of work until all the changes are made.

Branches, A11, A12

And how is this relevant to Alpha 12? Well, the Stonehearth team usually prefers to all work on the same main branch, all the time. We make incremental changes to our target features, and then check them in, resolving conflicts every day as we go. But when Alpha 11 got unstable, we realized that we didn’t want to further complicate the main code base (we call this branch ‘develop’) by adding all our experimental features to it (crafters, pathfinder, localization, etc) even if we could turn them off; more code usually means more instability! So though we all work on the main ‘develop’ branch to fix bugs, all the other pending A12 features we’ve talked about these last few weeks on Desktop Tuesdays have been made on branches.

The longer you work on a branch, isolated from the main code base, the more conflicts you must resolve before you can pull that branch back to the main one. And in this case, Chris, Albert, Yang, Tony, and I all have our own individual branches, with all the pet-features we’ve been working on whenever we haven’t been fixing bugs.

Here’s our branch merging strategy, summarized by Tony on our Stonehearth branded whiteboard here:

Basically, each feature is given a spot in a queue. The merging engineer does everything they need to do to push their feature into the main code base. Each other branch then pulls the new changes into itself, and fixes all conflicts. Then the next feature gets to go.

It’s long, mechanical, and sometimes very frustrating work. (“But this thing! It totally worked before I pulled your changes! What did you do to break my feature?” “I dunno! I didn’t even know about your feature while I was writing my feature!” “Stop throwing stuff at me!” “Get your own catapult!”)

Software development (beyond games, which are just one kind of software) is full of interesting challenges like this. Is there a way to stage features so that they conflict as little as possible? What conversations need to happen to make sure that Feature A doesn’t break Feature B whenever they combine? How can we make sure this code is written in such a way that it doesn’t need to be fixed whenever the stuff that depends on it changes?

This stuff is something engineers spend their whole lives figuring out, mostly through hard experience. In the specific case of A11, you can easily see how the unexpected complications with the backpacks and crates ripple out beyond themselves: because they discouraged development on the main branch, they created a situation where everyone now has to spend some time getting all their working code working with everyone else’s code, potentially introducing more bugs as people merge features that were developed independently.

I’m pretty sure that nobody decides to develop an indie video game because they have a passion for staging branch merges via source control. Still, it’s a good thing to have in one’s toolkit, because understanding how software goes together, and how to make it go together more efficiently, is what enables us to have as much time as possible to do the things we love–to build the game, together, with all of you.

Thanks for reading, and go play Alpha 11!

ONE MORE THING!

Yang is taking Tony’s stream Wednesday morning, 8/19/15, but she will start at 9:00am PST instead of 8:30am PST.