This section is deprecated due to newer versions. We ask that you don't use the information provided in this section, but read up on the most recent information available on this wiki or in the forum.
This is a tutorial on using Subversion to work with the Open Surge code, as well as the creation of patch files. While the info is currently targeted towards Windows users, it should be beneficial to all programmers not familiar with it already.
The good news is that it is not difficult to learn or do, and once you have made your first patch file you'll wonder why the heck someone didn't think of that before (they did in 1974).
Introduction to Revision Control
Revision control came about in 1972 as a way to keep track of source code changes made by multiple developers. Files are committed to a source code repository, from which previous versions can be retrieved. Over the years various applications handling this job have appeared, some still alive today with quite useful features.
One popular revision control offering goes by the moniker SVN but is more officially known as Subversion. In theory the Subversion package is a suite of tools designed with nearly all you would need to maintain your code project over space and time; in practice it's just a quick install and learning a few ubiquitous commands.
Step 1) Download and install Subversion from http://subversion.apache.org/
The link in Step 1 points to Subversion's new home which may change a bit still, but at the time of this writing there is a link to Binaries on the left side of the page and Windows files are near the bottom. There are presently five options for Windows, but the author of this tutorial only has experience with SlikSVN, so neither of them are endorsed over any other.
After correctly installing the SVN package, its time to get a hold of the Open Surge source code. We'll be using the command prompt for this job, so if you are not familiar with C:\> you're gonna get some practice now.
Step 2) Open a command prompt window
Vista users can shift-right-click the desktop and hit "Open Command Prompt Here". XP users will have to hunt for it in the programs folder or use the Run... box (just type "cmd" and hit enter).
Rather than teach you command prompts, go ahead and check out Microsoft's input on the subject at their Shell Overview page. To continue this tutorial you must be able to do the following:
- Change directories using cd command
- Make new directories using md command
When in doubt, search the web. Once you are ready, its time to get to work.
Step 3) Find a directory for the Open Surge files and change to it
The author has a folder on his computer at "c:\projects" where all his source checkouts exist. You should be able to make this folder on your own (or one of your choosing) but here is a simple set of commands to get it done:
cd \ md projects cd projects
Remember, you only have to do the second line ("md projects") once. After that, you should be able to hit the other two of those to get back to the projects folder you made.
Step 4) Check out the Open Surge project
Presently, the command to do just that is:
svn co https://opensnc.svn.sourceforge.net/svnroot/opensnc/opensurge/trunk opensurge
Working with the Open Surge code
You only have to check out the Open Surge code once, unless you want a clean checkout somewhere else. To grab the server changes and update your checkout, change into your Open Surge folder and run the svn up.
cd \ cd projects\opensurge svn up
You'll want to update your source checkout whenever you start coding for the day or after a significant break, unless you are confident nothing has changed.
Pulling a "diff"
Let's say you've sat down, updated the source checkout, and started working on a file such as src\level.c, making several changes that would be difficult to describe in a forum post. Go ahead and pull a diff of this file to see what your changes look like:
svn diff src\level.c
The results of this command are dependent entirely on what changes are made to that file, so if you just tried it on a fresh update you'll naturally get nothing. Assuming you do have an output of semi-intelligible quasi-text from that command, lets convert it to a patch. You can call the file what you want but the general idea is:
svn diff src\level.c > name_of_patch_file.txt
Now you have a patch file, which can be uploaded and shared with others working on the project. The process is as simple as it is straightforward.
Being able to pull a diff, store it in a file, and call it a patch is nothing special by itself, but the time it saves others who do want to see your work several minutes of hand-copying from the forum.
Also, patches tend to impress older programmers for some reason, possibly tickles their nostalgic bone. If you find yourself in an interview, just asking if they want changes committed directly or in patch form could be a landing point.
All said and done, contributions will be appreciated, and there is not any requirement which says code suggestions must be in patch form. Ultimately, though, the less time spent examining the impact of your work on the game, the more time will be available for making that impact a reality.