Ever since the Mission Architect (MiA) was announced, there has been a lot of talk and speculation about several things regarding the system, namely how do we save our work? Where is it kept? and How can we share our work in progress for collaborative projects?
All these questions (and many others, more or less related) aren't new for the rest of the world, they have been around for as long as collaborative projects with computers have existed (and even before, of course, but I mean in a computerized-digital form), and as such, there are solutions already for this. Work created with the MiA is saved locally on your computer, and for any project you will have a whole bunch of text files. How to manage them?
Enter
Subversion.
From Wikipedia:
[ QUOTE ]
Subversion (SVN) is a version control system initiated in 2000 by CollabNet Inc. It is used to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly-compatible successor to the widely used Concurrent Versions System (CVS).
[/ QUOTE ]
And also from Wikipedia:
[ QUOTE ]
Revision controls (also known as version control (system) (VCS), source control or (source) code management (SCM)) is the management of multiple revisions of the same unit of information. It is most commonly used in engineering and software development to manage ongoing development of digital documents like application source code, art resources such as blueprints or electronic models, and other projects that may be worked on by a team of people. Changes to these documents are usually identified by incrementing an associated number or letter code, termed the "revision number", "revision level", or simply "revision" and associated historically with the person making the change. A simple form of revision control, for example, has the initial issue of a drawing assigned the revision number "1". When the first change is made, the revision number is incremented to "2" and so on.
[/ QUOTE ]
So, what IS it anyway? In a tl;dr version: Subversion is a gigantic undo button with change tracking.
More or less.
You will be able to:
<ul type="square"> [*] Keep an historical archive of your missions, helping you know what happened when with
your comments.[*]Easily work on several different parts of your arc in parallel, and have systems to help you track all the different changes (say, for example, working exclusively on dialogs, then work on the map enemies, then work on the maps, and when you're done throw it all in together).[*]Help you track bugs. When something breaks, Subversion will have all your previous versions there so that you can compare and see what changed and how you broke things.[*]Allow several people to work on the same arc at once, by making it easy to see and track other people's changes and integrate it with your own work.[*]Share files without having to E-mail everyone with them. There'll be a central location where they can get the latest and greatest unpublished version. I mention unpublished, because if you publish it then anyone can play it anyway
[/list]
What this
isn't, and I'm putting it in bold for emphasis:
this is not a substitute for backups. it may make it easier to do backups by having all the files in a central repository, but it's not a backup! Some of the free web-based servers will do regular backups for you, others won't. Make your own backups anyway!
That said, roll up your sleeves and get ready to do some program-installing, because learning to use Subversion is not only handy for MiA, it's also an excellent skill that will help you in many other endeavors.
1. Installation.
I am going to be brief here. There are countless tutorials on the web on how to install Subversion. In some systems it can be as simple as "emerge subversion" while others can be a bit more annoying. For obvious reasons, I'll do a quick walkthrough for Windows.
Subversion needs two things: A server and a client. The server can be on your very own computer or it can be run on an independent server. You may be able to run it in your SG hosting server, there are some free subversion repository servers on the web too a quick Google will give you several links, and will save you the more annoying steps of installation. The client works under a lot of Operating Systems.
Download:
<ul type="square"> [*]A server:
http://www.visualsvn.com/server/download/[*]A command-line client (don't be scared! I'll explain in a sec):
http://www.sliksvn.com/en/download[*]A shell-integration client:
http://tortoisesvn.net/downloads[/list]
I said don't worry about the command line thing. In many tutorials and webpages explaining stuff about Subversion, they will tell you how to do things using the command line. That's why it's good to have it installed. However, for our little CoH arcs we will use the Tortoise SVN, which means you can manage your files directly from Windows Explorer by right-clicking them and choosing options from a menu, easy!
Anyway, on to the grimy details. Starting with the server (if you don't go for any of the free web-based ones that is), installing with the defaults is actually pretty good. Pay attention to the "repositories" location, that's where Subversion will be saving the projects and files! Also, make a note of the port in which it will be running, as you will have to let your firewall know that traffic will be coming through that port if you are planning on letting the world browse your computer that is.
After installation, I'd recommend running the server straight away, and then creating a new repository (Action -> Create New Repository...), name it CoH for example
. I recommend you choose creating the standard layout (i.e., click the only tickbox available). The VisualSVN webpage has lots of info about managing permissions and such (quite handy!).
Afterwards, install the other two files (the regular client and Tortoise). Again, default installs are just fine and dandy!
Installation is just THAT easy.
2. Quickstart Your first project.
So, after you have created the repository you can start adding things to it, right? Okay, let's get cracking. Files for the MiA are saved under four directories in your City of Heroes installation: Missions, Custom_Critter, CustomVillainGroup, costumes. The last one keeps just costumes in general.
So, we want to track all those directories.
Anyway, if you have rebooted at some point during the installation (which you probably have, this being Windows and all), open the VisualSVN server, should be in your Start menu somewhere
Now, see that URL on top? That's where the repository can be found. If you haven't done so yet, add yourself as user. Now, go into the project you created before (and if you didn't, create one), and inside the 'trunk' folder, create four new ones - Missions, Custom_Critter, CustomVillainGroup, costumes.
By the way, you noticed that it's a URL, right? That means it's there available for other people in the internet to connect to it! Give your IP and the port you're using to your friends and add them as users, then punch a hole in your firewall to allow traffic through that port. Presto! Instant server to share your missions with whoever you want, no clunky e-mail, no nothing! What's more important, they don't even need subversion just to get the files, all they need is a browser!
Anyway, back to business. Open Windows Explorer or My PC and head to your City of Heroes install directory/folder. Now, right click an empty part of the window, and choose the 'SVN checkout' option that has just been added by TortoiseSVN. You have to enter something like this:
http://www.walkiry.com/CoH/SVN%20Tutorial/svn1.jpg
I say "something" because the name of your computer will be different from mine. In any case, the URL of the repository is displayed quite neatly when you open the VisualSVN server, right at the top. It's a matter of adding the appropriate directory (in my case, adding /CoH/trunk).
Easy!
When you click OK, you will get a warning that the directories are not empty. This is a good warning and you should pay attention to it. Right now it's OK because we have just created the repository and it's brand new. If you are checking out a repository that is NOT new then any local file
with the same name as the one in the repository will be replaced. It may actually be what you want, or it may not
Once you have done this, you will have a bunch of neat looking icons instead of the usual ones. All the pre-existing files will be marked with a ? in the icon, meaning SVN has found that there're files there, but has no idea what to do with them. This is for a very good reason:
Subversion will not track files unless you specifically tell it to track them.
That means you can have the files from your SG repository being tracked, for example, while keeping your own personal files separate.
How cool is that?
Now that SVN knows where the repository is, let's start adding files.
Say, I have a mission I want to add. I go to the Missions directory, Select the File -> Right Click -> TortoiseSVN -> Add.
Ta-da! You have just added a file to your repository! Couldn't be easier.
Wait, there is actually nothing in the repository yet. That's because Subversion is more clever (or devious) than you thought. What happened is that we have done a change one of, possibly, many. Adding a file, or removing others, is merely one possible action, same as editing an existing file. Nothing NOTHING will get done until you
commit the changes. That's the point when you say "okay, I'm happy with the way things look now, make me a hard copy, right there". This is a very important concept, because it's the main difference between just moving files around and actually using a version repository. You need to commit the changes, and each commit can have
several changes.
We're not going to commit yet, let's do a couple of other things first.
One thing you don't want is for this to be done automatically. Remember that I said you could track changes with your comments? Well, let's add the option so that you get a prompt for comments every time. How to do it?
http://www.anujgakhar.com/2008/07/22...h-tortoisesvn/
Why reinvent the wheel? Anuj explains it crystal clear. Go to your City of Heroes folder and do it there. From now on, you get a prompt to add a comment to a file, with the minimum number of characters you wanted.
Another thing you may have noticed when you went to add the new mission file: There is an option that says add to ignore list. Now, select EVERYTHING in your City of Heroes directory EXCEPT the famous four folders. Right click -> TortoiseSVN -> Add to ignore list -> Ignore XX items (where XX is the number of items selected).
No more worrying about those files! If you don't like the little grey signs over the icons, you can get rid of them. Right click -> TortoiseSVN -> Settings, then select "Icon Overlays" on the left menu, and uncheck "show overlay for ignored items".
Now, go ahead and commit the changes. Go to the root City of Heroes folder, right click -> SVN Commit. Add a description, like, say, "Added my first files" and say OK. BE VERY DESCRIPTIVE. This is one of the most important steps. This is what you will read three months from now when you're trying to decipher what on Earth you did to make the carnies dance a Polka instead of shoot laser beams out of their noses. Be detailed, be descriptive, if you seem to go on forever with these it may be indicative that you may have to update with new versions more often. Click OK, and the log with changes will display.
At this point you should be able to see the files in the VisualSVN Server window. You may want to "Refresh" to see them tho (I blame Windows).
Also, if you "Refresh" the City of Heroes root directory you'll see a change in the icons: The modified directories will look nicely green instead of the danger red they had before. That's because you're up to date.
3. Tracking changes.
Of course, just adding things isn't what you want. Suppose I made a big boo-boo and deleted the wrong file, what now?
Right click -> SVN Update. Ta-da! The file is back!
Nice, huh?
If that doesn't work, Right click -> TortoiseSVN -> Revert is the safest, surest way to recover from any major screwup.
And if you screwed really REALLY badly, just checkout a previous version
There's a catch tho. If you have deleted a file, you'll get whatever was at the server last. But if you also modified several other files, be sure to send the to the server before you revert anything - or you may lose those changes too!
Also, if you are using your very own personal repository, then this isn't a big worry, but if you are in a collaborative project, the file may also have been updated by other people, if you checkout the latest version because you had deleted it, you may get a file different than the one you worked before - and mess up your versioning numbers.
That's why the Flying Spaghetti Monster invented revision numbers. See, when you update or checkout or commit, SVN will keep spitting a message like:
"At revision 9".
That's telling you what version of the files you're using. It's important for several reasons, which we will get to.
Let's imagine you are working in a collaborative project, or an old revision (there are reasons to do this, which, again, I'll get to later). You have a file that SVN is telling you is different from the one at the server. You want to figure out what's different, right? Well, you're about to meet the most awesome tool ever invented: Diff.
Select the file in question -> Right click -> TortoiseSVN -> Diff
http://www.walkiry.com/CoH/SVN%20Tutorial/svn2.jpg
What you have is a wonderful text editor with colour code showing where changes are. It actually is an editor, you can go and edit the file on the right side that's the file you have on your computer, your "working copy".
It's hard to make it easier to see changes, isn't it?
So, if someone has changed a file while you were away, you can get their file straight away. If BOTH of you have changed the same file, but in different places, this is where you can see where the changes were, and merge both your works into a single file with the works from everyone who modified it.
Always check the differences if the repository has advanced its revision number.
When the revision number goes up, someone has introduced a change. Check it out and don't overwrite it. If you had an older file and someone corrected a bug in the meantime, you could be reintroducing the bug.
Don't do that
4. Branching.
Branching is an interesting concept, but one that has the potential of helping you inmensely. It's also more complex, so you may want to work on it for a bit. Finally, I don't think it will be entirely necessary for MiA: Stuff is not that big or complex, and just with careful use of Diff and some communication (in the case of a collaborative work) should be enough. However, I'll try to explain it a bit.
Suppose you have a complex arc. You want a series of events for the boss fights, you want some custom critters, and you want some really cool text for the clues. That's a lot of work, right? Well, divide and conquer.
Note: This is one of the most important things for collaborative projects. Successfully managing branches and mergers is the key for smooth collaborations and seamlessly integrating the work from several people. Pay attention!
What is branching? Branching is, simply put, creating an alternate universe for your files. What will happen is that you will move the files to another place in the repository, where only you will be doing changes. The rest of the mission creation team can be working on the main branch. Heck,
you can be working on the main branch. Typically, branching is done so that you can work on a particularly annoying feature that is going to prove difficult.
To make it more visual, think of it as this. In a normal working day, you do the following:
Revision 1 -> 2 -> 3 -> 4 -> 5....
When you branch, you go like this:
<font class="small">Code:[/color]<hr /><pre>
1 -> 2 -> 7 -> 8 -> 9...
|
v
3 -> 4 -> 5 -> 6
</pre><hr />
It doesn't look like much, but think that you may be branching at different points, specially if there's more than one person working on this. If, for example, you are working on the bosses and their powers, then find out there's a typo in one of the dialogs, you may want to add the correction to the main branch as well as the one you're working on, without going and adding everything else. That way, if someone else (or you, if you get tired of trying to get the bosses' powers right and want to try something else) checks out to start another branch for something different, that correction is there.
Good practice tip: Use branching when you are going to work on something new, or something you don't know much about. This way you can keep adding versions to the repository that are
not working as you want them to. Try to keep the main branch with versions that more or less work, and use branching to keep track of changes that you know are going to break the mission(s) for a while until you get them right! Even for a single person, branching can keep things tidy, which is a great help.
Branching is cheap and efficient, and quite safe. Don't be afraid to use it. And if you don't like the way things go, you can delete the branch entirely and call it a day. Don't go overboard either and create branches for every minor thing. Making a branch so that you can correct a typo would be way over the top
Anyway, on to the meat. Say that at this point I want to create a branch, I'm going to do some fancy thingathingly on the mission and I think it's going to take me a while to get it right. So, I make a branch.
Select a file -> Right Click -> TortoiseSVN -> Branch/Tag
http://www.walkiry.com/CoH/SVN%20Tutorial/svn3.jpg
So, I'm going to be working on the thingalingy, and I'm saving it to the /branches/thingalingy directory in the repository, as opposed to the /trunk one.
Make sure you select something that is not the trunk here. Otherwise you're not branching
(To browse the destination of the branch, hit that ... button next to the "To URL". If you want to create a new directory and you should! - you can either right click on the "branch" folder and choose "add folder", or it's much more easy if you just do it from the VisualSVN Server window).
After you branch, SVN will nicely remind you of what you have to do next:
<font class="small">Code:[/color]<hr /><pre>
Command: Copy E:\City of Heroes\CohTest\Missions\Testarc.storyarc
to
https://Jupiter:8443/svn/CoH/branche...starc.storyarc, Revision 9
Completed: At revision: 12
Notice: Please note:
Notice: Your working copy remains on the previous path. If you want your next changes
Notice: to be committed to the copy or branch you have just created,
Notice: then you need to switch your working copy over to the new URL.
Notice: Use the Switch command to do that.
</pre><hr />
Well, let's do just that!
Right click the file -> TortoiseSVN -> Switch -> Change the URL to the one you just made (again, use ... to browse for it).
<font class="small">Code:[/color]<hr /><pre>Command: Switch E:\City of Heroes\CohTest\Missions\Testarc.storyarc
to
https://Jupiter:8443/svn/CoH/branche...starc.storyarc, Revision HEAD
Completed: At revision: 12
</pre><hr />
There we go, we are branched!
So, at any time you can move between the branch you just made and the main one. Also, if you have paid attention, you must have realized that
you can have different files in different repositories, you could have your SG missions tracked by your SG Subversion Server, while you track your very own local ones with your very own local Subversion Server. You can even get mission sfrom other people's Subversion Servers if they decide to share with you.
One word about merging, which I covered before briefly, but it's worth mentioning again, because it's the typical thing that gets all the newbies unless properly warned (I, fortunately, had an excellent mentor when it came to learning Subversion, so I was properly warned
). When you create a branch and work with it, the main branch is available for you or others to work on as well. So, when you are done with a branch, you should NOT replace the current copy in the server with your own, because you may override other people's works.
Remember the branch graph?
<font class="small">Code:[/color]<hr /><pre>
1 -> 2 -> 7 -> 8 -> 9...
|
v
3 -> 4 -> 5 -> 6
</pre><hr />
Say, you're done with your branch, it's time to merge it back to the main one! You go and put your file after revision 9... Bam! You have destroyed three revisions worth of work from other people (or, again, your own). What you do is, you start by
comparing your own version with the one right after you checked the branch out (in this case, version 7). You add the changes made in that version (and this is where you discover if there are conflicts with your own work!). THEN you take the merged file and compare it with version 8, and do the same, and keep doing it until you reach the last revision (also called HEAD revision). Then it's safe to make you own file the latest, and if everyone else comes with a modified branch, it's their job to do the same walkthough you just did
The OTHER way to do it is to, instead, check the main trunk regularly to see if anyone else has done any changes, and add those changes into the branch you have been working on. That way when the day comes and the branch is done, you can just go ahead and move the files (after you check that, indeed, you have the latest and greatests). I tend to prefer the previous method because it's : a) the same amount of work. b) you know at all times exactly how many changes you added (none! Until you add them all at once starting from the moment you branched). However, this second method is good if your work is very big, you don't want to fall too far behind but I don't think this is a worry for MiA.
Anyway, let's merge. First off, commit any final changes you made to your branch. Then, right click the file you want to modify -> TortoiseSVN -> Merge. Choose the "Merge a range of revisions". Then, with the ... choose the right file
in the /trunk, and then fill the "Revision range to merge" you can just leave blank, but it's better if you click "Show Log" and choose from the point where you branched to the latest version in the trunk. When in doubt, alway, ALWAYS check the log to make sure you're chosing the right revision (i.e., what revisions may have gone up since you started working on the branch), love the "Show Log" button.
Now that that's commited, switch back to the trunk the main version. To do so, simply right click -> TortoiseSVN -> Switch, then use the ... to browse to the trunk and the file. Just like we did before.
The reason to do this is that changes have to be merged
from the branch [/i]into[/i] the trunk. Making it so that it's always that way makes sure the merge will be consistent whenever you do it i.e., versions won't get confused and you may think your work is back into the main version when it actually isn't. At this point, though
After that, right click -> TortoiseSVN -> Merge. Choose "Reintegrate a branch", and in the following dialog make sure you choose the location of the BRANCH with all the new juicy changes that will be merged into your working copy of the main trunk. Like so:
http://www.walkiry.com/CoH/SVN%20Tutorial/svn4.jpg
When you click "Next" you will be taken to a page of options that works just fine with the defaults. I recommend that you hit the "Test" button to see if anything weird happens. If it merges successfully, you're good to go, hit Merge and call it a day.
Don't forget to commit!
5. This branching thing is way too complicated!
As I said before, this is a slightly complex thing that may not really be that necessary for MiA. Diff and just commit/update may be more than enough. However, if you take the time to learn it, it will prove awesome.
The TortoiseSVN page has a good bunch of info on merging:
http://tortoisesvn.net/docs/release/...dug-merge.html
And as you can see they point you to the Subversion book. This is an EXCELLENT source of info about Subversion.
6. Tagging.
Okay, this is a lot simpler than branching (well, it's kind of a special case). It isn't even strictly necessary, but it's good practice. When I mentioned branching, I talked of the "Branch/Tag" option. What is a tag?
A tag is merely a branch that is usually kept intact, it tends to represent something that has been released (in the case of MiA, a published mission). That way, you always have an exact copy of what's public, in case someone comes back with a bug. If there have been internal changes to the mission since release, it can be hard to track where the released version is. Instead of placing it in /branches, you place it in the /tags directory of the server.
As I said, this is just good practice. Treat it as another repository, and only update it if you re-release a mission - by creating another tag. It's simple and easy, and trust me, eventually you'll be thankful you did this.
7. That's it!
At least for now, that's it! There is a wealth of information on Subversion on the web. Just googling for Subversion tutorials will give you loads to chew on, many of them excellently written. I also recommend the Subversion FAQ and the book online:
http://subversion.tigris.org/faq.html
http://svnbook.red-bean.com/nightly/en/svn-book.html
They are
fantastic resources, and will answer a lot of questions that I probably rose by making things as clear as mud. I recommend at the very least reading the foreword in the Subversion book, because it's a great description of what it is: It actually answers questions that we, the users, have, not the ones the developers wish we would have.
8. Other version control systems.
There are many other systems which, like subversion, will let you track files and changes as you see fit. One that popped out during our discussions as a lightweight, simpler system (because it doesn't need server/client setup, it's just one program running) is Git:
http://git-scm.com/ .
While I have no personal experience with it, there is something you have to remember (and applies to more than just Git, it applies to pretty much all version control systems out there):
The principles to use Subversion, Git, and other systems will be practically the same. How you handle the repository, track changes, branch, merge files, pretty much all systems will do the same thing. They may do it in a "different" way, but the underlaying principles will be solid.
