Ivan

Version Control (part 3)

In this third article in the series about using version control, I'll cover using version control in a team, which is where it becomes one of the most essential tools to get to grips with in software development.

The story so far

In the first article, I was trying to write a small program in the jPoetry.NET language. I had written this:

I walked around by myself for a bit, feeling a bit lonely,
like a cloud floating over the vales and hills,
then suddenly saw some flowers;
they were cool.

A team rather than an individual

Now, my boss is worried that I have slipped behind schedule (and hasn't read The Mythical Man Month), so she assigns Billy Wordsvalue to help me. Fortunately, he's pretty good at the syntax and semantics of this programming language and we get on with our work. Billy and I are not pair poetry writing (we haven't read Extreme Programming Explained, or Pair Programming). We work on separate computers with our code checked out on our local hard disks.

Check in discipline

In order to check in my changes, when I'm working in a team do the following sequence:

1) run all tests
2) update, including doing any manual integration needed if there are conflicting updates (more about this later)
3) run all tests again if there were any updates. I like to run the tests before updating (i.e. step 1) because if the tests fail after I've updated then I want to be sure that the problem is because of something I've updated rather than because the tests would have failed even without an update. The tests have to run quickly if you want to check-in frequently.
4) I like to check through what I'm about to commit because I've got a terrible memory, and might leave some dodgy System.out, or worse, in the code.
5) update again - in case someone has checked-in while I've been running the tests and reading through the changes (having fast version control system is also important when checking in frequently.
6) if there were no incoming changes then commit¹, otherwise start from (2) again

¹I like the people making the check in to include their initials in the check in comment, so it's easy to tell who to ask if you don't understand some code or changes to some code. You can't rely on the login details when people are pair programming or when you have people swapping machines/logins as happens on many Agile projects.

Working in parallel

Billy edits the code as follows:

I walked around by myself for a bit, feeling a bit lonely,
like a cloud that floats on high o'er vales and hills,
then suddenly saw some flowers;
they were cool.

He goes through steps 1-6 and commits his changes (he finds that there are no incoming changes so his check in is easy). At the same time, I've been working and have edited the code as follows:

I walked around by myself for a bit, feeling a bit lonely,
like a cloud floating over the vales and hills,
then suddenly saw some flowers;
by a puddle,
they were cool.

Now I am ready to check in, so I do the steps:

1) "run all tests" - they pass
2) "update, including doing any manual integration needed" - I do an update, and subversion merges Billy's changes into my file, in this case without any conflicts as we have changed different lines. In practice, even on teams of a dozen developers, you don't get many conflicts. The result is:

I walked around by myself for a bit, feeling a bit lonely,
like a cloud that floats on high o'er vales and hills,
then suddenly saw some flowers;
by a puddle,
they were cool.

3) "run all tests again" - they pass
4) I check to see what changes I've made. Because I've done an update, the only changes shown are the ones I've made, not the changes that Billy made.
5) "update again" - Billy hasn't checked in since (1) so there are no more incoming changes
6) "if there were no incoming changes then commit" - so I commit.

Meanwhile, Billy has continued to work. He continues to edit:

I wandered lonely as a cloud
that floats on high o'er vales and hills,
then suddenly saw some flowers;
they were cool.

He goes through steps 1-6 again. The result of his update and check in leaves the poem as:

I wandered lonely as a cloud
that floats on high o'er vales and hills,
then suddenly saw some flowers;
by a puddle,
they were cool.

I edit:

I walked around by myself for a bit, feeling like a lost slug,
or a cloud that floats on high o'er vales and hills,
then suddenly saw some flowers;
by a puddle,
they were cool.

Now when I try to update, I get a warning that there is a conflict. Billy and I have both changed the first two lines. In cases like this, subversion can't work out how to merge the changes itself - it takes understanding to resolve the conflict. I manually resolve the conflicts and end up with:

I wandered around, feeling like a lost slug, lonely as a cloud
that floats on high o'er vales and hills,
then suddenly saw some flowers;
by a puddle,
they were cool.

which I think merges the best of Billy's work with mine. I tell subversion that the merge conflict is resolved.
I continue with steps (3)-(6) and check in.

We continue to work and end up with:

Mary had a little lamb,
its fleece was white as snow,
everywhere that Mary went,
the lamb was sure to go.

It's a funny old world.

Version Control (part 2)

Following on from Version Control Part 1, here's a short article on how to set up Subversion, a simple to use, yet "industrial strength", version control system. These instructions are only for windows NT4/2000/XP; installing and setting up Subversion on other operating systems is similarly simple.

For more about Subversion and how to use it, read this book.

Download and install Subversion

Firstly, download and run the windows installer (currently here).

Create a new, empty repository

Open a command prompt.

Execute:

svnadmin create c:\svnRepository

(or whatever you want instead of "c:\svnRepository" - the article assumes "c:\svnRepository"). This will create a folder c:\svnRepository that Subversion will use to store it's versions of your files. Do not add, delete or edit any files in this folder or any of it's subfolders until you know what you are doing. This folder is quite different than any folder where you have files that you want to put in version control.

Set up subversion server configuration

Edit c:\svnRepository\conf\svnserve.conf

and add the following at the end of the file, starting on a new line and with no spaces at the beginning of each line:

[general] anon-access = none auth-access = write password-db = passwords.txt realm = myRealm

and create a file "c:\svnRepository\conf\passwords.txt" containing:

[users] aName = aPassword

replacing aName with whatever login name you want for subversion and aPassword as some password.

This will allow password protected access to read and write to the subversion server running on your machine from any other machine connected to it (e.g. over the internet) once the subversion server is running.

Run the Subversion server

Execute:

svnserve -d -r c:\svnRepository

This starts the subversion server for the subversion repository you just created at c:\svnRepository.

Install Tortoise - windows explorer integration

Now install TortoiseSVN - download and run the windows installer (currently here).

Creating a new folder in version control

I'll only describe one simple scenario - please experiment with TortoiseSVN (maybe even read the documentation) to find out more. The steps described may seem like a long list, but really it's all very simple and doesn't take long.

Open a windows explorer.

Select c:\

Right click TortoiseSVN > Repo-Browser

Type url "svn://localhost"

This now allows you to browse what's in your subversion repository a bit like windows explorer (but your repository will be empty now). In this example, I'll show you how to create a folder for files that you want to version control.

Select "svn://localhost" in the TortoiseSVN Repository Browser

Right click Create Folder...

Type the folder name myProject.

Click OK on the "create folder" dialog and also on the "log message" dialog.

You'll now see that the folder "myProject" has been added to the repository.

Press OK in the repository browser to close it.

Using the version controlled folder

Now, in the windows explorer, select c:\

Right click Checkout...

For the URL of the repository, click the "..." button to the right of the URL combo box - this opens the repository browser.

Press the + to the left of svn://localhost to expand the tree view of what's in the repository and select myProject.

Press the OK button on the repository browser.

For the Checkout directory, type C:\myProject - this will be where the files that you will work with will go.

Press the OK button - then a dialog will say that the folder doesn't already exist and do you want to create it - click yes on this and OK on the checkout dialog.

Create a new file in c:\myProject called "thing.txt" with some text in it.

In windows explorer, select C:\myProject

Right click Commit...

In the "enter log message" dialog that is opened, you can enter a message in the top section that describes what you are adding or changing. In the lower section, there will be a list of files that have been changed or could be added to version control. In this case, there will just be the file "thing.txt" with a status "non-versioned". Click in the checkbox next to "thing.txt" and press the OK button. Then click on the OK button of the "commit" dialog.

Editing files

Edit the text in "thing.txt".

In windows explorer, select C:\myProject\thing.txt

Right click TortoiseSVN > Diff

This will open a TortoiseMerge window showing the difference between the current contents of thing.txt and the version as it is in version control - i.e. it will show the edits that you have just done.

Close this window. If you wanted to throw away your changes since the most recent version of the file in the repository, then you'd select the file and Right click TortoiseSVN > Revert.

Right click Commit...

In the "enter log message" dialog that is opened, "thing.txt" will already be selected, and the status will now be "modified". Press the OK button on this dialog, and on the "commit" dialog too.

In windows explorer, select C:\myProject\thing.txt

Right click TortoiseSVN > Show Log

This opens a Log Messages dialog. This dialog allows you to see what changes were made between any two versions (just select two versions and Right click Compare Revisions.

That's all I'll write about for the moment - I'm hoping that's enough to get you started. I'd strongly recommend just trying out the menu options of TortoiseSVN and reading some of the documentation before using subversion for anything real.

In the next article in this short series I'll write about using version control in a team, which is where version control becomes even more vital and adds to the scenarios described here and in part 1.

Version Control (part 1)

Version Control seemed like a boring beaurocratic irrelevance when I
heard about it at university. It sounded like something that I would
be subjected to in the big bad "real world" - nothing in it for me -
but I could see why it might be necessary. These days (since about 9
years ago), I consider it a liberating and useful tool that I wouldn't
be without either at work programming in a team, or at home writing
blog articles by myself. This is an article for those who don't feel
the same, or don't know what I'm on about.

In this article, I'll try to explain what is so great about version
control by means of an example. In a future article I'll explain how
to set up and use Subversion, a simple to use, yet "industrial
strength", version control system, to get the most benefits with the
smallest amount of effort.

Consider the writing of a small program, in this case in the language
"jPoetry.NET". First, I create a new text file somewhere called
"poem.txt".

I walked around for a bit,
then suddenly saw some flowers;
they were cool.

hmmm. Not very poetic. Nevermind, I'll save this in version control anyway.

Accidents happen

After such a long time working without a break - by my standards - I
go to get a cup of tea. While I'm in the kitchen, the cat sits on the
keyboard and deletes the file (particularly unfortunate considering
that I don't have a cat).

I retrieve the poem from version control and continue with my efforts.

I walked around by myself for a bit,
like a jellyfish floating in the sea,
then suddenly saw some flowers;
they were cool.

Still not great, but I check in again.

Version Control for Debugging

I edit a bit more:

I swam around by myself for a bit,
like a jellyfish floating in the sea,
then suddenly saw some flowers;
I was rather suprised to see flowers in the sea, but there you go.

Oh dear - I've really messed up the poem - it's not "working" any
more. Rather than continue to hack around with the poem until I get it
work, which would probably mean adding hack upon hack, I use version
control to help me work out where it all went wrong.
I look at what I've changed since I last checked in to see if that
gives me any clues (if I had a realistic number of changes then I
wouldn't necessarily be able to remember exactly what I had changed).
The version control system has a way to show me the difference between
what I've got now, and what I had when I last checked in.

I see the two changes - to the first line where I changed "walked" to "swam",
and the last line, where I really bodged up the poem when I was trying
to keep it working. Rather than continue, I "revert" the changes; i.e.
return to how the poem was when I last checked in and try again.

I walked around by myself for a bit,
like a cloud floating over the vales and hills,
then suddenly saw some flowers;
they were cool.

I like this new change - the poem works - so I check in.

Check what you are committing

I work on the poem a bit more, during which time I've put in some debugging code to see whether the poem is really working correctly:

I walked around by myself for a bit, feeling a bit lonely,
Console.writeln("the first line just about worked")
like a cloud floating over the vales and hills,
then suddenly saw some flowers;
they were cool.

Before checking in, I always check through my outgoing changes. For this check-in I notice that I left the "Console.writeln" in the poem. I don't check this in, instead, I delete that line and then check-in:

I walked around by myself for a bit, feeling a bit lonely,
like a cloud floating over the vales and hills,
then suddenly saw some flowers;
they were cool.

More soon

In "Version Control part 2" I'll explain how to set up Subversion, a simple-to-use but industrial strength version control system. In "Version Control part 3" I'll explain how version control helps when working in a team.

Many thanks to Nat Pryce for his constructive comments on this article.