CIS 3000: Introduction to Computer Game Design

Cornell Forge

In working on a project with a large group of students, you need some way to collaboratively manage your software development. You need a single place to store your code. You want some way to undo changes when another group member accidently deletes all of your hard work. And it might even be nice to have a bug tracker, to keep track of all the known bugs in the system.

In the past, we have let students fend for themselves on this issue. However, Cornell has finally provided us with a solution to this problem: Cornell Forge. This is a local version of SourceForge that does not require your projects be Open Source and is restricted to members of the Cornell community. In order to improve group development, we are requiring all students this semester to use this service.

Cornell Forge has a lot of bells and whistles. However the primary thing that you will use it for is version control. In version control, each member of the team downloads a local copy of the project files from the central server. If someone wants to edit a file, they first check it out from the server. When they are done editing (for the time being), they check in all of the changed files to the server. If there is a mistake, or the new version contains bugs, it is always possible to revert the code back to a previous version.

There are many different types of version control programs out there. For example, Perforce is the standard in the game industry. Cornell Forge supports Subversion (SVN). SVN is a bit old, but it is free and it gets the job done.

Using SVN

In order to use SVN, you must have an SVN client on your computer that accesses the Cornell Forge. These clients vary from command line programs to graphic front-ends to plug-ins that fit directly into Visual Studio. However, at their heart, they are all SVN programs and do roughly the same thing. When you use SVN, you should pay attention to the following features.

Checkout

Checkout is what you do the first time that you connect to a repository (e.g. where your files are located). It downloads all of the files in the repository, plus some additional files that let it track the changes you make. You only need to do this once for each new computer that you work on.

Add

If you are the first person to create a file, then you will need to add the file to the repository. Note, however, that this action does not actually add the file. It only flags it to be added later. Nothing will be added until you commit.

Commit

Commit is one of the two most important actions you can do in SVN. When you commit, you are uploading all (or at least those you select) changes to the SVN repository. Files flagged for addition will be added. Modified files will replace their original versions in the repository.

This is a powerful command, and you should use it with care. If you do not commit properly, then your repository may contain a "broken build" -- nothing compiles or works at all. Please see our guidelines below for how to properly commit.

One important thing to understand about the commit command is that every single commit is assigned a number. This number represents the version of the repository at the time of that commit. As commits are the only thing that cause the repository to change (remember, adding does not actually add), it is the only time these numbers are assigned. This is important when you want to go back to any earlier version.

Revert

Suppose you have decided that all of your most recent work is garbage and you want to undo it. As long as you have not committed the work yet (and you should never commit bad work), you can revert. This replaces the version on your computer with the latest one stored in the repository.

Update

Together with commit, update is one of the most important commands. It is both the most powerful, and the one that can cause the most headache. When everything is going right, update will pull down the latest version of the files from the repository and put them on your computer. It will also merge changes; if there have been some changes to a file that you have been editing, it will combine those changes with yours.

Merging works best when the changes are in different parts of a document. For example, if it is a source code file, then the changes should be in different methods. If the changes are in exactly the same place, then merging will fail, and SVN will complain about a conflict. It will provide you with a file that shows the two editted versions and ask you to resolve the problem manually. Once you resolve the conflict (and commit the result!), everything will be fine.

Merging only works with text files. For non-text files like art or music, SVN will not even try to merge changes. It will simply notify you that there is conflict and expect you to fix it yourself.

The update command has one more important feature. You can use it to "rollback" the state of your project. Did Bob make a really boneheaded commit? No problem, just rollback to an earlier version. To do this, you have to give the update command the number of the commit that you want to go back to.

SVN Clients

If you are hard core, you can use SVN from a command line prompt. However, we do not recommend that. There are a lot of nice graphical front-ends to SVN to make using it a lot easier. As this course is about developing games in XNA, everyone should be working on a Windows platform. We recommend that you use one of the following two SVN clients.

TortoiseSVN
This is the most popular SVN client for Windows. Several commercial tools are actually built on top of it. It is not integrated with Visual Studio, but is instead run as a separate program.
AnkhSVN
This SVN client is a free plug-in for Microsoft Visual Studio. It allows you to integrate SVN support directly into your project.

We will not give you an explicit instructions on how to use these clients. We refer you to the appropriate documentation. TortoiseSVN in particular has several very nice tutorials online.

SVN Guidelines

SVN by itself is not a silver-bullet. If you do not use it correctly, it can be no better than e-mailing code back and forth between group members (which is a bad, bad idea). Therefore, we are providing you with some words of wisdom to help to use version control effectively.

Use version control for everything

That includes art and music. If the group artist or musician is uncomfortable using a Subversion client, please contact the the course staff for help.

There is one exception to this. If the repository contains everything needed to compile the program, you do not need to put the actual executable in version control.

Always update before you check in

You have just spent an hour editing that file. While you were working, Joe made his own changes to that file. When you check in your new version, you get a complaint that the changes are inconsistent with each other, and the program fails. How do you resolve this?

If you update first, the update will merge Joe's changes in with yours. It will give you a list of inconsistent changes, and give you the chance to determine whose changes are best: yours or Joe's. Then you can commit a nice, consistent version.

Do not commit broken code

Please make sure that the project compiles before you check it in. No one likes to download a broken build. This problem typically occurs because you need to update before you check in. While your project may have compiled before the update, the changes from the merge may cause everything to break.

Take snapshots after each milestone

When you make changes to something in version control, it replaces the old version. You can always roll back, but this can be a pain. Sometimes, you want to keep an old version around to get to it easily. Particularly if something disastrous happens and you really screw everything up.

A snapshot is an older version of your game that compiles and is stable. Like the technical prototype. Or alpha release. To make a snapshot, create a separate folder in the repository with the name of that snapshot. Put a copy of all the files in that folder. And then you are to never, never, never touch it again.