What is the SVN?
What is the SVN you say? It's a system that allows multiple programmers to work together on the same code. They can be anywhere in the world and stay up to date with each other's changes. It also lets anyone browse the history of the files, seeing what changed and who changed it. Old versions can be pulled up easily, side projects (branches) can work in parallel with the main project (trunk) without breaking each other. When the branch is complete it can be merged back into the trunk with ease.
So now you can see why we use the SVN, but why should you? Well first off it's a very easy way for you users to get the latest and greatest beta (or alpha, or preview, or prerelease, or...) build of the mods you love. Don't fear, we'll still post official releases to the big sites (WoWInterface.com, ui.worldofwar.net and Curse-gaming depending on author preferences), this just allows the impatient people fast access to the most up to date code. Heck, I myself commit up a few things a night usually.
Software and Downloading
The supported method of downloading from Ace are the zip files. Please use this method first, it's the least load on the server, and the simplest for the end user.
There are a number of automated updaters available to download and unpack the zip files for you. They will scan your addon folder and grab any updates they can find.
The most popular updater is WowAceUpdater, but there are others out there.
Starting to like this SVN wackiness? Great! Want an even easier way to download? Go download a client:
- SVN Binaries (Windows, OSX, *nix. Command line only)
After you've installed a client you're going to do what's called a Checkout. Now normally a programmer will checkout the code he needs, edit it, and commit it back to the repo, you'll just be doing step 1 here probably.
If you're using TortoiseSVN, right click in explorer (anywhere should work), select "SVN Checkout". Plug in the URL for the folder you want to check out and the path you want it saved to on your computer. This is the exact same stuff as when you did it manually. Make sure the folder is empty or you'll get errors though! It should download and give you an OK message, now you're good to go. The next time you want to download this mod you can just right click the folder and select "SVN Update", your client should remember the URL it downloaded from.
If you are using the SVN Binaries, open up your console (Windows users can access this by going into Start -> Run... and typing in 'cmd'). Navigate to your World of Warcraft\Interface\Addons folder, then type:
svn checkout <url> <destination folder>
So for example, to checkout BigWigs you would type:
svn checkout http://svn.wowace.com/wowace/trunk/BigWigs/ BigWigs
Once you have a mod checked-out, updating is a simple matter of typing:
svn update <folder name>
So for the BigWigs example, you would type:
svn update BigWigs
Improving TortoiseSVN performance
TortoiseSVN will in many cases cause a big performance hit on your explorer operations, this is because of it's default recursive settings which are all purely cosmetic:
- Right click somewhere and choose TortoiseSVN | Settings
- Under "Look and Feel" make sure "Fetch status for context menu" isn't checked.
- Under "Icon Overlays" make sure "Show overlay icons recursively" isn't checked.
- In the new TortoiseSVN version, such option is called now "Shell" and is a radio button which you must check.
This section is for the mod authors only, if you don't know the first thing about editing mods then just head home now... nothing to see here folks...
Okay so you've edited a mod, or have a new mod you'd like to upload... great! Please read the SVN Rules and follow it's directions to get access.
Uploading a brand new mod is called Importing (gee descriptive name eh?). Go to the folder you want, right click, "TortoiseSVN > Import...". Plug in the repository path you want it to land in (usually http://dev.wowace.com/<name>/trunk/<addon>. The repository name for WoWAce is wowace, so to import an addon "FlingPoo" you would use the address http://dev.wowace.com/wowace/trunk/FlingPoo. Make sure you always enter a comment about what you're doing when you upload, then hit OK. It'll ask for your username, then send up the files if you have permission. Once you've confirmed this has worked you should erase (or move) your local copy and Checkout the files you just committed. This will let TortoiseSVN track the changes you make. If other people work on your mods you'll probably want to make sure to do an Update to download their changes before you work. TortoiseSVN will help you out if there are any conflicts (you both change the same lines of code).
Uploading an update is called a "Commit". This process is similar to an import, but only the changes made are uploaded. Tort will of course ask for a comment before you commit. If you've forgotten what you changed (I do this all the time!) Tort will show you a list of changed files. Double-click one to open it in the diff viewer. This will show, side by side, the "Working Base" (what you last pulled down from the server) and your "Working Copy" (the one you've changed). It'll highlight every line that is different, this is very handy for those with bad memory. You'll never have "and I'm sure I changed some other important things too..." in your patch notes again! Once you're happy with your notes just hit OK and your update is available for everyone.
A special note about Tags, Tags are essentially a snapshot of your code that is important. Most devs will tag their code just before they put out a release. Tagging is basically just copying the trunk folder over to the tags folder. It's not a complex process, and you don't have to do it if you don't want to, but it's common practice so you probably should.
Branching is an important tool when experimenting with new features. A Branch is basically an offshoot of the current trunk that gets developed separately and then merged back into the trunk at a later date.
To create a branch go to the folder, right click, "TortoiseSVN > Branch/Tag". TSVN then asks for the new location on the server, this will normally be http://svn.wowace.com/wowace/branches/<addon name>/<user name>. You may also select if you wish to switch to using the branch as your working copy. If the addon branch path (minus your username) doesn't already exist you will need to create it before you perform your branch. You can do this in Tort's Repo Browser.
You may freely switch between your branch and trunk copy using "TortoiseSVN > Switch...". Using this command will switch the two copies out on your local computer. This has several benefits. Including allowing development of a non compatible version and switching to the main for play. Or just allowing you to issue bug fixes based on the trunk while developing the new branch.
Finally when you are done and satisfied with your branch you may merge the branch back in with the trunk copy. SVN will attempt to reconcile any differences, if it cannot it will ask you to resolve them.