View source for User:RavuAlHemio/Tackling SDK updates with Subversion

(I'll probably keep this under my wing until it's clean enough. Please post inquiries and constructive critique to the [[User talk:RavuAlHemio/Tackling SDK updates with Subversion|talk page]] to facilitate this. Thanks. :-))

This guide details the specific usage of [http://subversion.tigris.org/ Subversion], a piece of source control software rather popular not only with members of the open source community, with the Source SDK. The [[Using Source Control with the Source SDK|theory and a specific usage guide for Perforce]] has already been written by [[User:chrisb|Chris Bokitch]] et al., so if you aren't going to be using Subversion, you might find slightly more generic information there.

If you like your version control integrated into Windows Explorer, take a peek at [http://tortoisesvn.tigris.org/ TortoiseSVN], which provides just that.

== Assumptions ==

Probably the worst part of each guide, we are going to assume that you have already set up a Subversion server at https://svn.example.org/mymod. (No, it's not a real address.) If you don't own/lease a server and/or lack the skills to set up Subversion, there are a few free hosting services for this purpose.

Additionally, we're assuming that you know a bit about source control systems already. If this is not the case, feel free to read the great ''[http://svnbook.red-bean.com/ Version Control with Subversion]'' book available at no cost on the Web. It should get you jump-started pretty fast.

Finally, the current version of the guide expects that you are starting from scratch. (Thousand apologies if you are not.) Later versions will probably fix this deficiency.

Even though prompts in this guide begin with a <code>$</code> sign, the commands should work on Windows too, if you have set your PATH environment variable correctly.

== Populating the repository ==

First off, we need to get the code into the repository. For this purpose, we create a new directory to host Valve's unblemished SDK code (this will make upgrades '''much''' easier):

 $ <b>svn mkdir <nowiki>https://svn.example.com/mymod/pristinesdk</nowiki> -m "Created pristine SDK"</b>
 Transmitting data..
 Committed revision 1.
 $ <b>svn checkout <nowiki>https://svn.example.com/mymod/pristinesdk</nowiki></b>
 A  pristinesdk
 $

The current folder now contains a near-empty ''pristinesdk'' subdirectory. (Subversion has some of its data stored inside already.)

Next, jet through the ''Create a mod'' wizard, extracting the source code into the ''pristinesdk'' directory. Once this is done, issue the following commands inside:

 $ <b>svn add *</b>
 A  cl_dll/
 A  cl_dll/alphamaterialproxy.cpp
 [...]
 $ <b>svn commit -m "Added newest Valve SDK code."</b>
 Sending        cl_dll/
 Sending        cl_dll/alphamaterialproxy.cpp
 [...]
 Transmitting file data........
 Committed revision 2.
 $

Valve's code is now inside your repository. (Remember the revision number, in this case ''2''; you'll need it when upgrading.) You mustn't change the contents of this folder between updates, or the whole upgrade process will become exponentially harder. Instead, create a trunk for your own mod:

 $ <b>svn copy <nowiki>https://svn.example.com/mymod/pristinesdk https://svn.example.com/mymod/trunk</nowiki> -m "Branched for mod code."</b>
 Committed revision 3.

If you want to keep the clean code on your machine and just create another folder with the code for your mod, run checkout again, this time with the trunk's URL. Since it's enough when one developer keeps around the clean code on their machine to perform upgrades when Valve releases new drops, you can switch to your mod code directly:

 $ <b>svn switch <nowiki>https://svn.example.com/mymod/trunk</nowiki></b>
 [...]
 Updated to revision 3.

You should now probably rename the ''pristinesdk'' to the name of your mod, since it's time to go berserk on the code!

== Updating the SDK ==

''pristinesdk'' and ''trunk'' have probably grown far apart from each other... and it's time for a family reunion, assuming your team has agreed on a time when they'd be ready for such an event. (Don't forget: your team is your most valuable asset.) Fortunately, if you haven't done anything to ''pristinesdk'', the process shouldn't be fraught with much error (except for the conflict-solving phase).

Begin by just deleting '''every single file''' from ''pristinesdk'' (not the <code>.svn</code> directories!) without letting Subversion know. Next, extract the new SDK code into the folder again. Run the following and watch for the output:

 $ <b>svn status</b>
 M  dlls/items.h
 ?  materialsystem/stdshaders/unlitgeneric_hdr_dx9.cpp
 !  dlls/ancient_hacks.cpp
 $

''M'' means that the file has been '''m'''odified, ''?'' means that Subversion doesn't know about the file and ''!'' means that the file has been deleted without Subversion's knowledge.

You don't need to do anything about the ''M'' files. The ''?''s have to be added, like so:

 $ <b>svn add materialsystem/stdshaders/unlitgeneric_hdr_dx9.cpp</b>
 A  materialsystem/stdshaders/unlitgeneric_hdr_dx9.cpp
 $

You can supply multiple files to ''svn add''. For the ''!'' files, you do the same, but use ''rm'' ('''r'''e'''m'''ove) instead:

 $ <b>svn rm dlls/ancient_hacks.cpp</b>
 D  dlls/ancient_hacks.cpp
 $

You do this until the status letters of all files turn into these:

 $ <b>svn status</b>
 M  dlls/items.h
 A  materialsystem/stdshaders/unlitgeneric_hdr_dx9.cpp
 D  dlls/ancient_hacks.cpp
 $

If a folder is empty after the SDK update (except for the <code>.svn</code> subdirectory), you can probably remove it too, unless you really like empty directories or you're using the directory in your mod and don't want to do any restructuring.

 $ <b>svn rm dlls/deadcode</b>
 D  dlls/deadcode
 $

<div style="border:1px solid black;padding:0.1em;background-color:#eef">If you want to see if any files are still pending, you can use ''grep'' on UNIX or ''findstr'' on Windows to filter ''svn status'''s output. For example, to show only new files pending marking, do this:
 $ <b>svn status | grep ^\?</b>
 C:\modtrunk&gt; <b>svn status | findstr /b ?</b>
and to find deleted files to mark, do this:
 $ <b>svn status | grep ^\!</b>
 C:\modtrunk&gt; <b>svn status | findstr /b !</b>
</div>

When all changes are included like that, you can "go for it":

 $ <b>svn commit -m "Updated Valve's SDK to the 2006-08-04 code drop"</b>
 [...]
 Committed revision 1024.
 $

Now, it's time for what might be the hardest part: the merging itself. Go into the directory where the trunk is checked out, get yourself a caffeinated beverage and then issue:

 $ <b>svn merge -r 2:HEAD <nowiki>https://svn.example.com/mymod/pristinesdk</nowiki></b>
 [...]
 $

Now, forget the number 2 and memorize the number 1024; you'll need ''that'' for the next update.

The merging process obviously must have generated some conflicts.

 $ <b>svn status</b>
 C  dlls/client.cpp
 $

Every line starting with a ''C'' has changes made by Valve and your developers that don't match. Directions on resolving these situations can be found in the Subversion Book; suffice it to say that, once you are done fixing the conflicts, you can mark it as fixed:

 $ <b>svn resolved dlls/client.cpp</b>
 Resolved conflicted state of 'dlls/client.cpp'
 $

When your janitor job is done and you have made sure no massive crashers were introduced (while sipping the tenth cup of caffeinated beverage), put on your flame vest (something ''ought'' to break) and speak the incantation:

 $ <b>svn commit -m "RED LETTER DAY: Valve SDK update merged with mainline. Please forgive and correct oversights and mistakes."</b>
 [...]
 Committed revision 1025.
 $

If you are really paranoid, you can branch the trunk using ''copy'', merge the pristine SDK with that branch, fix all crashers, merge the code back with the trunk and delete the branch used for merging again. Base the decision on your skills with Subversion, the number of coders on your team, how much work the coders have done during your fixing spree, and how much of your mod's code you think the SDK update will break.

Good luck.