Thursday, December 18, 2008

Tortoise SVN - tag & merge tutorial

Since it's quite confusing how to branch/tag and then merge a branch with the production code - here's a short tutorial on the issue. Note that the strategy of tagging and merging presented below is probably not the only possible, however it works in practice.

I assume that a SVN repository is created, the SVN server works and Tortoise is installed on the client machine.

Step 1 - Import local files into the repository

Start from creating a local directory with application files in it.


You need to "put" the local directory into the SVN server. In SVN language this is called "import". Click the Application directory with the right mouse button and choose TortoiseSVN/Import from the shell context menu.

After you click "OK", the local directory is imported into the SVN. Note, that I use /trunk subdirectory to actually store files there. This is because we will create other subdirectories in the same repository and these subdirectories will contain tags of the code.

Step 2 - Checkout managed repository from SVN back to your local machine

Now you need a new, fresh location on your local filesystem dedicated to work as a local image of the repository. Create a fresh directory, let's call it ApplicationCode, right click on it and choose "SVN Checkout" from the context menu.

The Checkout operation retrieves the contents of the repository and creates a local image of it which can be then synchronized with the repository using the "Update" and "Commit" operations.

Local filesystem after the checkout operation looks like this:

Delete the /Application folder, it's no longer needed.

Step 3 - Continue working on the /trunk line of the code

This is what people find confusing.

Should I continue to develop application using the /trunk line? Or should I rather create a new /development line?

Well, there's no single answer to this question, however the advice is as follows: use the /trunk line to make any changes you want and whenever you make a release to clients - create a tag.

Let's then continue to work on the /trunk line for a while - create a new document "c.txt" in the /ApplicationCode directory and commit changes into the repository (right click on the /ApplicationCode and select "Commit" option).

Step 4 - Tag whenever you release your application to clients

A great day comes and you release your application to your clients. Click the /ApplicationCode with the right mouse button and select TortoiseSVN/Branch-tag option from the context menu. This invokes the "Copy (Branch/Tag)" window where you should give a name to the tag's directory.

Let's assume that the tag's name is "tag1" (this is where it turns out that putting files into /trunk subdirectory is important - both /trunk and /tag1 will be subdirectories of the same repository directory on the server).

Click "OK" and SVN will happily inform you that "your working copy remains on the previous path. If you want your next changes to be in the just created copy then you need to switch over to that copy path. Use the Switch command to do that."

Step 5 - Oops, a bug's been found. Go back to the Tag and fix the bug

As you continue your work on the /ApplicationCode directory and Update/Commit changes into the /trunk subdirectory in the SVN, a day comes when a bug is found in the code released to your clients. This is where you need to go back to the code, make changes and synchronize changes with the /trunk line.

As the message from the previous step says, you could use context menu's "TortoiseSVN/Switch" command to switch the code in the local /Application directory. However, this is not required!

Instead, I prefer to restore the image of the SVN's /tag1 into just another, fresh directory in the local filesystem. Let's then create /ApplicationCode_Tag1 directory in the local filesystem and checkout the /tag1 into it (just like we did in Step 2).

Now, let's fix the bug in the code retrieved from the /tag1: we'll modify the b.txt and create d.txt.

Commit changes from the /ApplicationCode_Tag1 local directory. Note that changes are stored only in the /tag1/ subdirectory in the SVN.

Step 6 - Merge the patched code with the /trunk line

This is the most fun part - we'll merge changes applied to the /tag1/ line of the code with the /trunk line of the code.

First, invoke the TortoiseSVN/Merge function from the context menu on the /ApplicationCode directory.

Note that the text in the lower groupbox correctly informs you that the result of the merge will be stored in the /ApplicationCode folder which contains an image of the /trunk folder. However, what you are supposed to do is to specify the From: and To: sources correctly.

Let's leave the To: untouched and click the "Show log" beside the "Revision" in the From: section.

Here you see that one of the revisions is printed with blue color - this is the number of revision which had been active when the tag has been made. Remember the number (1101 in my case), cancel the log window and put that number in the Revision textbox in the Merge window:

Do a "Dry run" where you can inspect changes which are about to be made to the /trunk subdirectory. In our example you'll learn that the b.txt is going to be updated and d.txt is going to be added. Click "Merge" and inspect the contents of the /ApplicationCode folder:

Happy SVNing!

Tuesday, December 16, 2008

Application Architecture Guide 2.0 from Patterns & Practices

The Microsoft's Patterns and Practices group continue their great work on the Application Architecture Guide. You should definitely check out the newly released Beta 2 version.