Development:Subversion

From Damasca

Checking out

To checkout the code, you'll need the svn client installed, or alternatively (for a more intuitive interface) TortoiseSVN.

Assuming that you're using TortoiseSVN, you will want to create an empty directory somewhere to hold your working copy of the source. Enter it, right click somewhere, and select "SVN Checkout" from the context menu. In the checkout dialog, enter

https://damasca-tck.svn.sourceforge.net/svnroot/damasca-tck/trunk

as the URL of the repository and click OK. All being well the trunk of the code will be downloaded to your machine.

If all's gone well, you should have a copy of the source code and the tools to build it. Note that compiled versions of the code are NOT in the repository - nor should they be. To produce a build of the code, you can either use the Visual Studio project, or the NAnt build script.

I'm going to cover NAnt here, as most of you won't have VS, and those that do will be able to work out how to build it, I'm sure =).

• Firstly, open a command prompt: Start > Run, type "cmd" and click OK.
• Change to the working copy: Type "cd PATH_TO_WC" and press enter, where PATH_TO_WC is the path of the working copy you downloaded, e.g. "cd \Projects\Damasca"
• Type "build production" and press enter.

All being well it should compile everything, and create a "build" folder in your working copy. In there will be the latest version of the server, client and map editor. All the resources to run them will have been copied by the build script, so you can go ahead and run the engine.

Repository overview

The SVN repository is partitioned into three main folders - trunk, branches and tags:

• /trunk contains the latest relatively stable version of the code. The trunk must be buildable most of the time (ideally all of the time), and once unit tests are place, pass tests at all times. As such, only non-breaking commits should be made into trunk.
• /branches contains development that is running separate to the trunk. See Branching later in this document.
• /tags contains snapshots of releases, and other milestones. For instance, /tags/1.0/ might contain the code required to build our 1.0 release. Tags are created from the trunk once the trunk has reached the requirements for that milestone.

The trunk, each branch and each tag have the same set of folders within them. These are:

• /lib: All external library dependencies that are required to build a working copy of the engine.
• /resource: All game resources required to build a working copy of the engine (Python, XML, bitmaps etc).
• /src: All source code for the engine, map editor and unit tests for both. Note that only the engine code is in here - game code belongs in /resource.
• /tools: All external tools for building or testing the engine. (NAnt, NUnit etc).

Building the engine also creates a /build folder. This is a generated folder, built upon the contents of the other folders. It should not be committed to the repository.

Commits

Only those files which are needed to produce a build should be committed to the repository - this includes C# source files, Python scripts, XML data files and other game resources. Executables, object files, personal files (Visual Studio suo files for instance), everything in the build folder, and other intermediate files should not be committed.

The only exceptions to this rule are external libraries (things in 'lib'). As these are needed to produce a working build of the engine, it is required that they are provided, often in binary form.

Game resources (Python scripts, images, XML data etc) should be committed to the 'resource' folder (the NAnt build script will copy them as required to 'build').

For reference, I use the following global ignore list in TortoiseSVN (set in TortoiseSVN Settings):

*.suo build bin obj *.obj *resharper* _ReSharper* *.csproj.user

Commits should generally address one issue - if when describing the commit there is a list of things that have changed, see if they can be committed individually. (This is not a rule, just a guideline).

It should go without saying, but commits should have meaningful descriptions. The diffs can get quite large, making finding the purpose of a commit difficult to do without a useful comment :).

Mailing lists

Our mailing lists are hosted by SourceForge, and we currently only have one mailing list - Damasca-tck-commits.

Damasca-tck-commits sends an email with details of each SVN commit made, when it was committed.

You can subscribe to Damasca-tck-commits by going to https://lists.sourceforge.net/lists/listinfo/damasca-tck-commits.

Branching

Most development will occur in /trunk. However, in order to keep the trunk buildable and not require that developers disappear for long periods of time working on their own working copies, it is recommended that for large feature development or refactoring, a personal branch is created from the trunk. These branches are allowed to be unstable, so developers are free to make what commits they like (as long as they adhere to the rules declared in Commits). For more information on creating branches and merging them back with the trunk, see the SVN RedBook on Branching.