Question Subversion, SVN Tutorial

Search for the SVN Basics tutorial if you need it.

By Xiu,

If you’re serious about developing a MUD, a version control system might just be your next best friend. Currently, tbaMUD uses SVN as part of their development platform, which fits right into what I was using to control my own source code! Although, I certainly appreciated the advantages of working with a version control system in tbaMUD and my custom source code, I ran into a number of gray areas. For me, that dangerous fog of war was the layout of my repository. In hopes that I can save some people a few steps, I'm going to lay out a repository structure that can maintain the developers custom source code and the public tbaMUD release versions.

Here's a quick check before we move on:
1. Your experience with SVN. If you haven’t got your hands dirty with Subversion, read through Jeremy Osborne’s SVN tutorial.
2. Second, I use a Linux environment using the Ubuntu 9.04 server. All SVN commands are done through the standard SVN command line client in this example.
3. Topic Coverage: Creating repository layout and how to keep your custom code up to date against tbaMUD public releases.
4. What's not covered: I won’t be touching on installation or the access models, which require more details than appropriate for the scope of this tutorial.

Creating a Repository
Note: In the following and sections thereafter I’m using direct repository access over an ssh terminal session into my server. If multiple people will be accessing the repository, forget about using this access method and switch into http(s), svn, or svn+ssh.

What backend should I use?
If you browse the subversion manual , you’ll see a big section dedicated to the Berkley DB and FSFS models for the repository backend. I wouldn’t put much time into contemplating this if you’re a beginner. Yet, It’s worth noting that by default Subversion began using FSFS in version 1.2. If your version is 1.1 or earlier (svnadmin -–version), I’d check into upgrading into the latest stable release. So....you'll be using an FSFS backend by default, which in most cases will work just fine.

In the sample above I created a repository named devrepos in my home directory, pretty painless.

At this point, It’s tempting to jump straight into importing a source copy into your new repository, but I strongly suggest you check the SVN config options first. After creating your repository you should have a folder named .subversion. Inside this directory you’ll find a file named config, which has a number of options you can set. You should carefully look over the entire file, but I’ll hit on three so we get an idea of the configurable options available.


NOTICE!
The spacing in conjunction with column number in the configure file DOES matter. If you're using an option it must begin in column[1]. If a new line is required, continuation begins in column[2]. A formatting reference note can be found in README.txt, also located in the .subversion folder.

global-ignores - There are a few different ways to ignore files in subversion. However, this ignore option is special because of the global scope value attached to it (There is also a subversion global-ignores for the system, but any values set in your local home subversion config file will take precedence).

In the above sample I’ve added .plr and .objs to be globally ignored. Don’t get carried away here and begin adding uncommon/infrequent data types, specific file 'ignores' can be accomplished faster and easier using commands in the SVN client.

commit-times - The commit-times will add some overhead in your repository, but it certainly helps if you butt heads with another user that’s committed a revision from an outdated copy of the source (surely you wouldn't make the same mistake).

Properties - SVN properties are best described as being subversioned metadata. SVN uses a number of different property types, which can result in the management of a repository that much easier. On the other hand, it can be a slight nuisance having this active during the initial import of your code. I set up some additional values for the world files.

Directory Structure Layout:
I'll make this part short and sweet. The correct answer is, whatever best fits the scope of your project. Directories names have absolutely no baring on how the repository will treat them. Hold on though, unofficially, you'll see a good number of repositories set up like so:
In this layout we would import our main source code into the trunk directory. If a new project or test source code was being developed, a copy from the trunk is brought into a new branch. Finally, tags make life easier by taking snap shots of specific revisions during the source code distribution life-cycle (okay, doubt we'll be distributing our custom source code, but don't ignore making a tag here and there).

FINALLY! We get to the good part!
Alright, what I'm going to demonstrate is how you can manage your own custom source code, while also managing (with lots of help from Mr. subversion) new/modified source code additions from the tbaMUD releases. What we're talking about is essentially patching in new source code with a utility that has a pretty damn good idea of how it should be arranged. Okay, let's start!

My directory structure:
Okay let's setup that new repository.

Change into tartmp and grab the previous & current release versions of tbaMUD.

Okay, time to slow down for a minute and explain what we're doing and how things will be laid out. In this example my custom code base will be named redsun. My source, redsun, will be using the tbamud-3.59 release. I've decided to use the "unofficial standard" directory layout for my repository.

Obviously, the public tbaMUD release is not part of our project, but we still want to patch in the updated source into our project. In the Subversion book a completely separate project branch is created, which they label 'vendor'. However, my project is fairly small and I don't want to spread my repository directories out. Thus, I'll be adding a tbamud directory into the branches root. Each version I add in the branches/tbamud branch will be created as a tag (I want to keep my tags directory open for my own source code snap shots). With that tidbit, we're off punching keys again!

Change into the importme directory and unpack version 3.59 (The version redsun will be using).

Now we're going to import into the stock tbamud branch. Notice that the Subversion import command recursively recreates our path and any directories not already in the repository? Make sure you run this command inside of the importme directory, which should only contain the tbamud-3.59 source code directory.

Now we're going to tag the current version as 3.59 for the merge performed down the road. Finally, copy the current tbamud version into our main branch. This is the custom source code that's now "branched" off from the tbaMUD project (Yea, if it looks like we're doing things backwards, we are! Just keep going). Okay, a few months go by and what do you know?!? tbaMUD version 3.60 has arrived. Of course we want the additions, we just need to manage a way of patching it into our existing source code. Before we worry about that though, let's grab the 3.60 version and import it into our repository.

This part use to be a bit of a mess, fortunately, someone developed a hand dandy little script named svn_load_dirs.py to automate the process. Because of licensing issues, you might not have this script under /svn/tools. If a subsequent find brings up nothing, just download the script svn_load_dirs.py.in and rename it svn_load_dirs.py.

Okay we need to make a slight modification to the script. You'll want to figure out where your svn is (which svn) and than use an editor to change the following value in the script:

You'll probably end up with something like this:
Now move the svn_load_dirs.py into the importme directory and change into the directory when ready for the next step!

Unpack the tbamud-3.60 tar
IMPORTANT NOTE!
If you still have any other directories laying around in importme apart from tbamud-3.60 and svn_load_dirs.py you should remove them.

Run the svn_load_dirs script to automate a merge between version 3.59 and 3.60. The script will move the 3.60 into the current directory structure and make a new tag named 3.60.
Remove tbamud-3.60 and checkout a local copy of the redsun source code. We'll name the working source copy redmoon

Okay, here comes the make it or break it command!
Change into the directory redmoon. You'll now perform a merge of the changes between 3.59 and 3.60 on your source code.

Chances are, you'll run into a few conflicts that you'll need to resolve. A diff tool is available to resolve these conflicts if you should run into such a problem. After resolving any conflicts, DON'T FORGET TO COMMIT YOUR CHANGES back into the repository!

Okay that's it! Your changes are merged and your good to get back into the source code. The only thing I'd suggest is running a backup using the svnadmin hotcopy command.

I hope you didn't get lost along the way, as we did fly through the commands towards the end, but if you did...

Check out the Vendor Branches over at the svnbook page.

That concludes things for me, hope you you learned something new. At any rate, if you should decide to go fourth and make your own SVN repository, best of luck!