Guard Duty: A Development Retrospective - Dev Diary #3
Source Control Strategy
Howdy! This post is a bit of a techy one – seeing as I’m more an artist than programmer I’ll try to briefly summarize the process before handing over to Andy to explain the gritty details of it all.
Source control is super important when working in a team: it allows you to keep track of all the changes made to the game files and, if needed, revert back to previous versions of each individual file. It also means that more than one member of the team can be working on the project simultaneously. However, AGS has some of its own hurdles when it comes to that.
We use a service called BitBucket to host all of the core game files for Guard Duty, with the help of a front end client/application called SourceTree. SourceTree is an application that communicates with the BitBucket server, making it easy to keep track of all the changes to the files and allowing us to push updates after making them and pull updates from one another.
Due to the nature of how AGS works, there are occasional issues we run into with conflicting files, mainly the acsprset.spr and game.agf files, both rather large files that store global data not specific to individual locations, cutscenes etc. Andy is mostly able to fix these issues when they crop up with some sort of black magic wizardry, but it is something we have to be aware of when we’re both working on the game simultaneously.
On that note, I will hand over to Andy to go into a little more detail:
Getting Guard Duty working with BitBucket
I was really happy with how easy it was to set up, get the game files in and make a couple of test changes. The point of this post is to give you a quick crash course in source control (in particular Source Tree, which is the Windows/Mac client that works best with BitBucket).
So, without further ado:
Online source control server where every version of Guard Duty is stored. Includes an automatic changelog and comparisons between the old and new versions of every file between every update.
The Windows/Mac client that lets you Pull things from BitBucket and Commit/Push things to there.
(Also known as Repo) Basically a project – a collection of files. Guard Duty is our Repository.
The act of making a copy of a Repository – either from the server to your machine or vice versa (you’ll probably only need to do this once, unless you want a copy on Windows and another on OSX).
The act of taking something from BitBucket. This could be a single file that you didn’t have before (eg because I added it) or an updated version of a file that you did have. This is how you stay up to date with changes in the Master copy.
Think of this as ‘Save game’. When you’ve made a change that you’re happy with, you Commit it. This takes your working copy and adds the changes to the version SourceTree knows about.
Generally, a Commit will be a single packet of changes for a specific thing. Let’s say you added backgrounds for the mountain pass and also added dialog for the Drunken Monk – these are separate things so should ideally be Committed separately. This makes it easier for others to see what’s happened and also easier to roll back specific changes without affecting anything else.
Committing changes saves them to your SourceTree copy of the game files. When you’ve Committed one or more changes, you’ll see a number next to the Push button in SourceTree. This indicates how many Commits are waiting to be Pushed to the shared copy of the game – you need to push them before I’ll be able to see them.
In most cases you’ll probably want to Push immediately (there’s a checkbox in SourceTree that lets you do that when Committing) but sometimes you might want to wait until you’ve made a few Commits before Pushing (eg, you might want to add backgrounds, characters, objects and dialog for a certain area before any of it’s available to me).
Once Commits have been pushed they’ll b e uploaded to BitBucket and will then be available for everyone to Pull and see for themselves.
Add a file you’ve created to the SourceTree copy (takes effect after you’ve Committed and Pushed the change).
Remove a file from your copy and the SourceTree copy (takes effect after you’ve Committed and Pushed the change).
Adds any files you’re missing compared to the SourceTree copy, and Removes any files you’ve deleted locally from the SourceTree copy.
You might sometimes hear about making branches, or see them in BitBucket. This is a way of creating a duplicate of everything so you can safely work on experiments without affecting the Master copy (you can then merge them into Master afterwards if you want). Branching is especially useful when working on more than one distinct thing at a time, as it lets you concentrate on your own work without seeing all the changes going on everywhere else. Merging branches is normally straightforward, but it’s at the point of merging that you might get conflicts (where one change would overwrite another one), and you’ll have to choose which one to keep.
Those are the main terms you’ll come across regularly and the ones we use for Guard Duty.
So now, here’s a step-by-step to joining BitBucket, getting SourceTree installed and a hooked-up copy of your game onto your machine.
1. Join BitBucket and create a team (let’s call it ‘yourteam’ for now). Then create a ‘yourgame’ repo (where ‘yourgame’ is the name of your project). If you make the project private, only people you invite will be able to access it.
- Go to Bitbucket.org
- Get the rest of your team mates to sign up as well. Once they’re in you can invite them to join the team.
2. Install SourceTree
- Go to Sourcetreeapp.com and download the Windows/Mac version
- Open the installer, follow the instructions…
- Use these settings when the questions come up:
3. Pull the yourgame Repo into SourceTree
- At Bitbucket.org go to Clone and choose Clone in SourceTree.
- Your browser might ask you for permission to make an external protocol request – let it.
- SourceTree should open at the Clone menu.
3-A. Set the Destination Path to somewhere new on your machine (this is where your game project will be stored).
3-B. Create a bookmark called yourgame.
3-C. Hit Clone.
3-D. SourceTree will start downloading everything to the destination path. Now you’ll have a copy of all your game files that are hooked up to BitBucket. SourceTree will stay updated with the files and will show you what’s changed – it keeps itself refreshed. It’s best to keep SourceTree open all the time so you don’t have to wait to see review changes, Pull files or Commit and Push.
4. Merge your changes to the BitBucket version
(This step will bring BitBucket up to date with your local copy, keeping the server copy in sync)
4-a. Pretty simple – work on your game as you would normally.
4-b. Be sure that you are updating the game files in the BitBucket folder we have just setup.
4-c. Switch back to SourceTree and you should see a bunch of changes in the Working Copy Changes pane. Changed files will have a yellow marker instead of a green tick like this:
Green tick = unchanged, up to date with BitBucket
Yellow dots = changed, not update in BitBucket until you Commit and Push
Red stop sign = removed, but still in BitBucket until you Commit and Push
Blue question mark = untracked (you should Add these)
4-d. There might be lots of yellow dots, maybe even all of them are now yellow, but that’s okay for this time.
4-e. If there are any blue question marks, highlight them and click the Add button. You’ll see a progress bar and then they’ll change to green ticks.
4-f. Highlight something in the Working Copy Changes pane, press Ctrl+A to select all, and then click the Commit button. The Commit window will appear and you should see that all the files you modified or added have their boxes checked.
4-g. Enter a message that makes it obvious what the Commit is for (eg ‘Bringing BitBucket repo up to date’) and hit Commit.
4-h. Cue progress bar. It might take a little while depending on how big the committed files are.
4-i. When that’s done, click the Push button (should now have a ‘1’ by it).
4-j. When that’s done, revisit Bitbucket.org to see your Commit in the Recent activity feed.
Et voila! Hopefully that went smoothly and you now know all you need to use BitBucket and SourceTree!