Ok, I'm an EVEMon Developer, now what?

Warning: This guide assumes that you have reasonably high comfort level with C# and Visual Studio, and zero experience with SVN.

First of all, go get C# Express and TortoiseSVN.

Now, pick a place where you'd like to put your EVEMon code. I use \My Documents\Visual Studio 2008\Projects\EVEMon. Create that directory. Now from that directory, right click and select "repo browser" from the Tortoise menu. Enter "svn://evemon.battleclinic.com/EVEMon/EVEMon/" for your url.

You can now see the repository. There are three directories here - tags, branches and trunk. Branches hold developers individual branches. If you're a developer working on a crazy feature that will take some time to implement (say, G15 keyboard support), you may consider making your own branch, and then merge it back in when the time is right. Tags hold historical versions. There's no difference between tag 1.0.25.4 and revision 22, but tags give us a nice, pretty way to see specific old versions. The trunk holds the main source code, and it's what I'll deal with first

Checking out EVEMon

From the repository browser, right click on "trunk" and select "check out".

http://evemon.battleclinic.com/images/svn-walkthrough/checkout.png

You'll be asked which directory you want to use for your working copy of EVEMon.

http://evemon.battleclinic.com/images/svn-walkthrough/working.png

Now you're wondering why it's EVEMon/EVEMon/trunk and not just EVEMon/trunk, right? Because we have multiple projects in the EVEMon repository. EVEMon holds the code for the program itself, and Documentation holds the public website.

Anyway, hit OK and tortoise will take its sweet time checking out the project to your computer.

Fixing a bug

Now it's time to fix a bug. First, open the solution and run it, just to make sure you got everything. For an example, let's say you're going to add yourself to the list of developers on the about window. How rude of you!

Open the file "AboutWindow.cs" in Visual Studio and add your name.

http://evemon.battleclinic.com/images/svn-walkthrough/edit_vs.png

Now then, compile and run the program to make sure it works... yep, looks like it does.

http://evemon.battleclinic.com/images/svn-walkthrough/changed.png

Now you're about ready to commit... but wait! Before you add something to EVEMon, you should open a ticket to your change, so that we can track its progress and rate its importance... and get someone to undo it if you really screw things up. Select "new ticket" from the trac menu and type in all the pertinent data.

http://evemon.battleclinic.com/images/svn-walkthrough/newticket.png

For milestone, pick what you think is appropriate. If it's a new feature that's pretty simple, set it for the next development build. If it's a non-crash or non-blocking bug, set it for the next release build. If it's a big deal and you're not sure what to put here, leave it blank, or enter the furthest build out. One of the administrators will probably change this anyway, to fit your ticket in to our milestones.

Now you have a ticket - whew, you're off the hook. Time to make a patch file.

Submitting your changes

Browse to your working copy and select "create patch" from the tortoise menu.

http://evemon.battleclinic.com/images/svn-walkthrough/makepatch1.png

Your files will be selected for you. Choose an output location and generate the patch. If you inspect your patch, you'll see things that look mostly familiar.

http://evemon.battleclinic.com/images/svn-walkthrough/makepatch2.png

Now go attach your patch to your ticket.

http://evemon.battleclinic.com/images/svn-walkthrough/makepatch3.png

And then add a comment saying what you've changed. You can see my sample patch here and leave a funny and/or snarky comment on ticket #28.

In a little while, an EVEMon DevAdmin will come along, read your ticket, check your patch for sanity and for any nefarious code, and then either leave you a comment requesting modifications or commit the patch to the repository.

Grats, you just fixed your first bug!

Getting other people's changes

Getting other people's changes is a snap. Simply right click on your working copy and select "SVN Update" in the tortoise menu. I'm not even going to provide a screenshot, because if you can't find that option, you have no business submitting patches!

When you do an update, you'll see a list of all the changes made since your last update, and it will look something like this. You can see that Eewec has been busy. Since SVN uses atomic commits, the entire repository has the same version number, even if you only change one file.

http://evemon.battleclinic.com/images/svn-walkthrough/update.png

This means that no matter what you do, we can always roll back the repository. Every single time a change is committed, we have a snapshot of the entire repository... so while we'd prefer if you don't make stupid mistakes, we know that stupid mistakes will be made, and we've made them before, and it really will be OK in the end.

If you manage to catch your mistake before you make a patch and all that, or you just want to get rid of your changes, you can use "Revert" to undo any changes you have made. Between revert and update, you should never have to do a checkout more than once.

Ok, great, but I'm one of those DevAdmins, how do I commit things?

Ok, so someone has submitted a patch that integrates a Mr Coffee into EVEMon, and you really need a cup of joe... how do you get that patch in there?

First, go to the patch page and download the original .patch file

http://evemon.battleclinic.com/images/svn-walkthrough/originalpatch.png

Save this somewhere convenient, then right click on it and select "Apply Patch" from the tortoise menu, and give it your working copy location. You'll see all the files changed in the patch and the diff'd copies of the two files. Any file that the system can't easily patch will be displayed in red in the file list.

Before you apply the patch, you must sanity check it. Read all the changed lines. You don't have to completely immerse yourself in the submitters plan, but at least check for stupid mistakes, potential performance problems, and nefarious code. If you submit a patch that sends everyone's password off to the Band of Brothers, I don't care if you made it yourself or just applied it, you will lose all your EVEMon rights.

If the patch does not apply correctly, you have two options, either read the patch file and apply it by hand (easy for small patches) or go to the ticket and leave a comment like "hey, I need you to recreate this patch against revision 35 or higher" or "your patch software is poorly written". Remember these two things: 1) you're not required to apply any patch, ever. You can always escalate it, drop me a note, reject it outright, I dont' care - I'll back you up. 2) EVEMon is not yours. if someone submits a patch that adds a feature you'll never use, but the patch is well formed, apply it anyway, or pass it off to another DevAdmin.

Uploading changes

Uploading changes is simple - browse to your EVEMon working copy and select "svn commit" from the tortoise menu. You must enter a log message. Even if your log message is as simple as "#28 Resolved", enter something so we know what you were up to. It's really easy.

http://evemon.battleclinic.com/images/svn-walkthrough/commit.png

Remember: Include the issue number in your commit comment like "#28 Resolved" (be sure to unse the '#' too). This will automatically link the commit to the Trac issue.

Now you should close the Trac issue that you have just submitted a fix for. Open the issue and set it's status to fixed with a comment like "Fixed in change set [43]". Remember to use the '[xx]' and them the Trac ticket will link directly to the Subversion change set.

Locking/Unlocking

If you're making a lot of changes to some really critical pages and don't want to risk conflicting with someone else, you have the option to lock and unlock files. Use this option sparingly and carefully. If you hold a lock overnight, or you think you need a lock for longer than an hour or maybe two, it's time to think about making your own branch.

http://evemon.battleclinic.com/images/svn-walkthrough/locks.png

Never steal locks. Bring a lock that you think should be stolen to the lead dev's attention and let him deal with it.

If you lock the entire repository, I will personally pod you. FYI.

Branches

If you have some changes to make that will take a while, say you're rewriting the network infrastructure or adding support for a specific piece of hardware, you should consider making your own branch. This will allow you to have safe, source-controlled development and visibility and contributions from the community without inflicting your half-realized vision on the people that, deep down, really don't care.

Making a branch is easy. Select "copy to" in the repo browser:

http://evemon.battleclinic.com/images/svn-walkthrough/branch1.png

And enter a URL for your new branch:

http://evemon.battleclinic.com/images/svn-walkthrough/branch2.png

You'll be prompted to enter a log message. Enter a log message! Branches without log messages get pruned!

You'll see your branch pop up in the repo browser. You can see my branch here.

Now you'll need to use the switch command to move your working copy over to the branch.

http://evemon.battleclinic.com/images/svn-walkthrough/branch3.png

This works pretty much like you'd expect. Man, this is a lot faster than CVS.

Now you can go in and commit/update/revert as much as you want without disturbing anyone else's actions.

Merging your branch

This is tricky. Do not assume that you know what you're doing. I know everything so far has been easy and straightforward, but here there be monsters.

After you've made all your changes - and you're still on the branch copy - commit everything. Once your working - branch - copy and the branch are synchronized, use the switch command to point your working copy at the trunk once again, and do an update.

Now go ahead and select Merge from the tortoise menu. Consider your input here very carefully.

http://evemon.battleclinic.com/images/svn-walkthrough/branch4.png

This step is not intuitive. I suggest you read this as well as the tortoise svn help if you feel uncomfortable.

Consider a merge as "playing back" all the changes you made to the files. You are playing back the changes on your branch from revision whatever (36 in this case) TO the latest version - this covers all the changes you made while branched. You are playing back these changes into your working copy - which is a copy of the trunk.

Once you've merged and resolved all the conflicts, commit your changes and you're done.

WHOOPS!

So you made a mistake - no problem. The merge tool can help you undo whatever it is that you did. Use the "playback" to play back your changes in reverse. For example, let's say I want to revert all the changes made between right now (revision 36) and version 1.0.25.4. Open up the merge options and find the 1.0.25.4 revision in the log.

http://evemon.battleclinic.com/images/svn-walkthrough/branch5.png

Now you want to playback all the changes from the current version TO revision 22. You're going to rewind the repository.

http://evemon.battleclinic.com/images/svn-walkthrough/branch6.png

Diff, merge, done. Your working copy is now rolled back. Commit your copy to roll back the entire repository.

You forgot something!

Ask your questions below or on the forums and I'll see that they are added to this document. Also, look for answers in the Tortoise documentation - it's really not too shabby - and post your findings here for everyone.