Source-Forge and how to get your copy

[bovi]

Here's a very basic guide to how you can use version control. Feel free to ask questions too, and I'll update this guide (I don't visit this forum extremely often, so don't expect immediate response).

BASIC SETUP
First you need to download the client. There is a Tortoise client for both CVS and SubVersion (SVN), you want the SVN client as the repository is this kind. Download this from http://tortoisesvn.net/downloads. There are loads of other clients available, but these instructions assume you're using Tortoise.

Then, you need to install it. Do that in the default location, or anywhere else you prefer, it doesn't matter. Once this is done, you will have gained some items in the context menu. When you right-click files/folders in explorer, you will see this:


Find the place where you want to download the current build from the repository! It can be any folder, but the best place is probably a clean 1.2 M2TW directory, so you can load the game using it. Right-click this and select SVN Checkout.

NB! The link seen in this image will not work, so don't use that! It is only meant to illustrate how to use Tortoise. The real link is https://italia-invicta.svn.sourceforge.net/svnroot/italia-invicta/trunk. You can download the build without credentials, but you'll need to supply a username and password to make changes. See Alpaca's post below for how to get write access.

You don't have to do this, but when you've started downloading the files from the repository, you really should configure Tortoise to only scan this (these) folder(s) for up-to-date status or it will slow down your computer immensely when navigating in explorer. You do this by right-clicking anywhere in the explorer and selecting TortoiseSVN=>Settings. Find the Icon Overlays menu. Enter this in the "Exclude paths" field:

c:*
d:*
e:*
f:*
g:*
h:*

You should add any other drive letters you may have too. Then enter the folder(s) where you're downloading the files to in "Include Paths", with an asterisk (*) behind it.

BASIC USAGE
To ensure that you have the latest version with everything that everyone has submitted, right-click the folder and choose SVN Update. It will check all files and subfolders for what has changed since you last updated, and tell you what it's doing to get you up-to-date. If you have uncommitted changes and update, it will automatically merge non-conflicting changes.

To change a file, simply do the changes you want, then rightclick either a file (for single commit) or folder (for all content under it) and choose SVN Commit. Always double-click the files you change in the commit dialog to check that only the changes you expect are made. Make sure to write a comment so people can see what you've done with it! This last bit is extremely important or there will be all sorts of misunderstandings.

To add a new file, create the file in your file system, then right-click and choose TortoiseSVN=>Add. You will have to commit in a separate operation afterwards.

If you make changes to a file on your local system and later decide you want the old file back (before you've committed it), simply delete your file and do an SVN Update on its containing folder, and Tortoise will retrieve it for you.

To rename a file while leaving it in the same folder, use TortoiseSVN=>Rename. It will ask you for the new filename. You'll need to commit in a separate operation afterwards.

To delete a file, use TortoiseSVN=>Delete. You'll need to commit in a separate operation afterwards. If you regret your decision, before committing you can delete the containing folder and do a new SVN Update. If you have committed you'll need to find the file in the revision log and restore it.

ADVANCED USAGE
But what happens when someone else changes a file at the same time that I am working on it?
That's okay. By using the SVN Update command, it will automatically merge all the changes others have done to your own working copy. If you choose to change the same lines, however, it gets a bit more tricky. Tortoise will tell you that there is a conflict that you need to work out before committing your changes, and markup your file with some not-so-simple signs of where the conflict is. A good tool for seeing what is changed in each file is invaluable here. UltraEdit/UltraCompare is excellent, but not free. WinMerge is free and used by many, and there are many other tools as well. Tortoise has one of its own, but I don't know how good that is. To set up this diff/merge tool, right-click in any explorer, and choose TortoiseSVN=>Settings. Under "Diff Viewer" you can set your tool of choice.

Yeah, I got that above, but I'm absolutely sure I've got the right thing and want to ruthlessly overwrite the others' changes!
First, be absolutely sure indeed. Otherwise go through the merge process. To overrule everyone elses changes, do this:

• Rename your file to something temporary.
• Do a SVN Update. The latest file from the repository will be downloaded and Tortoise will know that you have the latest one so there is no conflict when you make your changes.
• Delete the file again (normally you'd use this to merge the changes instead!)
• Rename your file back
• Commit

I want to see the different versions we have had of a given file or
Someone screwed up a file and I want to see what changes have been made!
Right-click the file and choose TortoiseSVN=>Show log. Right-click the revision you want to compare and select "Compare with working copy". Or select two revisions (be patient as it loads the change list) then right-click and choose "Compare revisions".

I screwed up a file and I want to go back to a previous version!
Committing bad files is something that should be avoided as much as possible, as it may slow down everyone until we find out why your change made the game crash, but it's bound to happen plenty of times. Thankfully the actual reverting isn't all that hard: Right-click the file and choose TortoiseSVN=>Show log. Right-click the revision you want to restore to and select "Revert to this revision". Commit it and voila! It's back where it was.

I want to move files to another folder.
This will lose the history of the files, so should be used sparingly.

• Move the files where you want them to be
• TortoiseSVN=>Add them to the repository
• SVN Update the old folder, it will reload your files
• TortoiseSVN=>Delete the files in the old folder
• Commit all changes

There is an alternative way to move stuff between folders using the repository browser, which I think retains history as well, but this is the simple way.

[alpaca]

Thanks, SVN is already set up fine - however we won't give anonymous write access. People can create patch files or ask me to be added to the dev list at SF.

The URL to get the latest version of the mod via SVN is:
https://italia-invicta.svn.sourceforge.net/svnroot/italia-invicta/trunk

If you intend to help us work with the mod, check it out to your M2TW directory (as bovi kindly described above) and you should be set up fine with a fresh folder called Italia_Invicta and the necessary batch and config file to launch the mod.
Once you verified it works, any changes you made will only be made to your local copy, because, as I said, I don't want to allow anonymous write access. Instead, you can create a so-called patch file. To do this, right-click on your Italia_Invicta directory and select TortoiseSVN->Create Patch:



After this, you will be presented a dialog asking you which files to include. Only select files you changed here.
Then a file selection dialog will pop up in which you can select a name and folder where to store your patch file.

Once you did all this, Tortoise will create the patch file from your working copy. Upload that file somewhere and send me a PM with information about what you changed and which revision (SVN revision) you based it on - and of course a link to the file.
Please also try to make sure that you work with the latest revision to create your patch.

If you want to participate on a more regular basis, I can also set you up as a developer at sourceforge. To do this, you will have to register an account there and then send me a PM with your account name. I will then review your application and decide if I'm fine with giving you write access (shouldn't usually be a problem). In that case, you can use the commit option as bovi described it above.

[bovi]

Tried to check out now. It works but seems to be a lot slower than the EB repository, perhaps that is because it talks encrypted with https? Is there any possibility of downloading over the svn protocol instead (IE get a svn://server/project/path link)?

[alpaca]

Tried to check out now. It works but seems to be a lot slower than the EB repository, perhaps that is because it talks encrypted with https? Is there any possibility of downloading over the svn protocol instead (IE get a svn://server/project/path link)?

Well on SF I've only seen https mentioned. Exactly how slow are we talking here? I got dl speeds of 130KB/s on average which is alright really.

I don't expect too many people to use the SVN repository anyways, most players will download the mod via different means once we make a release snapshot which I hope will be hosted on multiple servers while the SVN is probably hosted at one location.

[bovi]

I didn't measure the download speed, just noticed that the EB serves at least 6-7 times the speed. It doesn't matter though. It gets down eventually.

Which version of M2TW is this mod for BTW? You may notice that there's a placeholder field in the guide I posted.

[alpaca]

I didn't measure the download speed, just noticed that the EB serves at least 6-7 times the speed. It doesn't matter though. It gets down eventually.

Which version of M2TW is this mod for BTW? You may notice that there's a placeholder field in the guide I posted.

1.2 and 1.3 seem to be pretty identical, I'd say 1.2 or higher or something

From what I heard (or rather didn't hear) so far, Kingdoms seems to be downwards compatible so you can use the kingdoms.exe, too. It's currently for 1.2 anyways.

Thanks for compiling that guide by the way, I was just about to do it when I saw you already posted one.

[bovi]

It was a simple enough task to adapt the EB guide .

Instead, you can create a so-called patch file.

I hope you know what you're doing here. You personally will get lots of work to manage this (depending on the rate submissions come in, of course). While I'm not entirely sure how the patch system works, I think you'll also have to manage concurrent updates, merging submissions from several people manually, which SVN otherwise would do automatically. I hope I'm mistaken though. The patch system might understand which changes are made from the revision in question, rather than overwrite any changes made by others when a new file is patched in.