Version Control for Dummies - part 3

This will be a three part series. Part 1 is aimed at the project leader. It explains why you need version control and how to set it up. Part 2 is aimed at the developer who will need to work with the version control, so covers how to use it. Part 3 is about conflicts and other important topics.

Introduction
The version control is working, its being used ok. This is looking at some of the other features and a very common issue: conflicts.

What is a Conflict?
Take a case when you have two developers 'Fred' and 'Jim' both working on the same set of code.  We will assume they both get copies of the code & work on their machines adding different features.
When it comes times to commit back to the version control, this is when problems occur.

Fred commits first and there is no issue, after all he is working with the most recent copy of the code.

But when Jim want to commit what will happen?

If you are using a shared directory approach, Jim's code will just overwrite Fred's (not good).  Instead, the version control detects that Jim's code was based upon an older copy of the code and will not allow it to happen:

This is known as a conflict.

You can find out a bit more about this using the 'show log' command, and then do a compare your current code against the code stored in the version control.

This will provide a graphics difference comparing the two copies of the code. (Looks complex, doesn't it?)

Resolving the conflict
There are basically 3 ways to solve the conflict:

1. Jim can delete out your own code, then do a update from the version control and replace all his code with Fred's newer copy
2. Jim could move his code out of the way, get an updated copy of the code and try to copy/merge his changes in (good luck)
3. Jim can let the version control system merge the code together (which is hopefully not too painful)

If none of these sound good, thats because they are.  But remember, the alternative was just to blindly overwrite someones else code.

First you need to update the code to get it up to the most recent version (done before, not covered)
You will get a warning message like this:

It warns you that there is a conflict which needs to be resolved.
If you look at your hard disk, you will see a set of files:

The .mine is your original code, the .r4 & .r5 are the other copies of the code (in this case version 4 & 5, you will have other numbers).  The original file will have been replaced by the merged code which looks a bit like this:

If you know how, you can edit this directly and fix the code, but its easier to instead right click and use 'Edit Conflicts' which gets the merge program up.

The code in the top left is the 'most up-to-date' code from the repository.  The code on the top right is 'your code', and the code at the bottom is where you put the merged code.
There are a number of helpful features to make it a little easier:

This allows you to just copy the block of code from one side or the other or have them both.

VITAL: Once you have finished making a merge, load the code back into your compiler and recompile to make sure there are no errors in the code.  Just because it merges, doesn't mean the code is good.

Once the code has been checked, its time to commit the new code to the repository and move on.

Backups
One of the great things about version control systems is it keeps a complete copy of all the code.  But what happens if the server goes down?
If usually possible to backup the repository, here's how to backup an SVN http://stackoverflow.com/questions/2302592/how-do-i-back-up-a-remote-svn-repository

Getting a certain copy of the code
Again another task you might want to do: Get last weeks code.  To do this, just use Checkout, but instead of getting the 'HEAD', you can specify a given revision in the dialog box.

Branches & Merges
Its possible (though I just about never do it). To branch the code off, then you can work on two versions of the code (the main trunk and the branch).
Possible, not required, probably not advisable.

Conclusion
Thats about all I have ever needed to do with the version control systems, and overall it has served me well.
Hope this gives you a good idea of what its all about.

Happy coding,
Mark

Version Control for Dummies - part 2

This will be a three part series. Part 1 is aimed at the project leader. It explains why you need version control and how to set it up. Part 2 is aimed at the developer who will need to work with the version control, so covers how to use it. Part 3 is about conflicts and other important topics.

Introduction

You have version control.  Either the team lead told you you use it, or you understand how useful it is. Or perhaps you just joined a sourceforge project and you need to get access to their repository.  Whatever the reasons are, this post is looking at how to use SVN (in particular tortoise SVN) in your development.

A few terms

See: http://betterexplained.com/articles/a-visual-guide-to-version-control/ for a good summary.

I'm using the SVN terms as it will help later

• Repository: The 'shared directory' where the code lives, usually on a hosted server somewhere
• Import: take some brand new code & put it into the repository
• Check out: Get a fresh set of the code (usually the latest version) from the repository onto your local machine
• Update: Update the code on your local machine with the latest version in the repository
• Commit: Copy the code from your local machine into the repository
• Conflict: What happens when you try to commit some code and someone else has already made a modification to it

You will need

• A copy of Tortoise SVN ( http://tortoisesvn.net/)
• The URL of the SVN repository (the project lead will know this)
• A username & password (probably)
• Its worthwhile each developer having their own account, it encourages more responsible behaviour, as each commit has your name attached to it

The First Check Out

We need to get the latest code to work with, so this is where we start.

Get yourself a suitable directory.  It doesn't need to be 100% empty, but it cannot have a directory with the same name as your project.

Right click on the base directory and SVN->Check out

For the repository name, give it the information that you were given (remember, your project lead needs to set up the repository and give you the URL of it). As you want to copy the whole directory, you need to also give a directory name. I.E. we are copying https://whatever_the_SVN_repository_was/trunk/project_name

to d:\work\project_name So we will get all the code we need in a new directory.

(PS. The HEAD revision, means the latest copy).

After we hit OK, the SVN will get the latest copy of the code, create the directory and put all the code in it.

Currently its just the readme, but we will add some code later.  If you have a look on the hard disk, you will see the files added with a little green tick icon, which means they are up to date.

We now have the latest code.

General Usage: Adding, Ignoring and Committing

OK, so we have a version control up, what next?
Write code of course...
<some time later>

What next?
Lets have a look at my directory right now:

I have added in a Visual C++ project and put in a bit of code.  But life gets a little bit more complicated.
I don't want ALL of this stuff into the source control, mainly all the temp files and stuff, but especially the 100MB temp files which Visual Studio likes to generate.
As for knowing what to add & what not to add, this is down to the individual programming environment/language.  But in my case, I want to ignore the following:

• Debug and Release folder
• The .NCB, the .SUO and the .user files

Therefore I right click on them and mark them to be ignored.

After that, I add in the files I want to add again by right clicking.

You notice how it is now marked with a + to show its been added.  

However this does not mean its in the repository yet, that will not happen until we commit the directory to the server.  We do this by selecting the directory and doing a commit.

This will show which files are changed (& will be sent to the repository), at the same time it will show up which files are unversioned (not added or ignored), for you to decide what to do with them.  You can just right click & decide to add or ignore them.

(If you want to know what the changes are, just right click on the file & select 'compare')

Very Important: Use the text box to add some comments to explain what you did.  You want to know what other people have been doing to the code, so give the same feedback for them.

Most of the time it should work fine, unless you are working on old code.  In which case you may need to do an update (see below).

General Usage: Viewing and Updating

What happens if the others are working on the project and you need to find out what is going on?  Well, select the directory (or file), right click and select 'check log' which will give you the current history of the project:

Remember I said about adding the comments when you commit? Well you can see the comments listed here.
You can 'check for modifications' which will show you if your code if the most up to date, or if others have made changes to your code:

In this case, it seems that someone have updated one of the files, so what I can do is 'Update' to the latest copy of the code.

General Rules for use with Version Control

1. Never check broken code into the version control, test it first
2. Don't check in generated files (object code or similar), just the original source.
• It should be easy to regenerate the files from the source
3. Make sure you are careful with what you add into the version control, don't add in junk.
• On one project, someone added a 200MB movie files into the version control. I was very unhappy with them
4. Try to minimise the amount of non-text files which you add into your version control, as most systems don't handle them well & they take up a lot of space (compared with code)
• Some teams run version control for the code and then use a shared drive for art assets
5. On a similar note, If you are going to add art assets in, only add in the final items in a form which is useable in the project
• Don't put in your raw photoshop files, just the final exported bitmap
• Keep the raw photoshop files in the shared drive
6. It should be possible for someone to check out a complete your code from the version control system and build it without errors.
• Check it from time to time to make sure its still working
• There is a concept known as continuous integration http://en.wikipedia.org/wiki/Continuous_integration which automates this process

Conclusion

There are quite a few other items which I could cover (reverting, comparing and such), but these are the most common operations you need.
In part 3, I will cover dealing with the issues.  In particular what happens when two people try to change the same piece for code at the same time?

Until then, Happy Coding,
Mark

 

Version Control for Dummies - part 1

This will be a three part series.  Part 1 is aimed at the project leader.  It explains why you need version control and how to set it up.  Part 2 is aimed at the developer who will need to work with the version control, so covers how to use it.  Part 3 is about conflicts and an other important topics.


The problem?
When you are writing programs on your own its quite easy to do, but what happens when there are two (or more) people working on the project together.  What do you do?

1. Everyone hack the code & hope
• Never going to work
2. Pass latest copies of the code about using email/thumb drives
• Sort of workable, but its hard to know which bits have been updated
• And you never know where the latest copy of the code is
3. Everyone writes their own code & gives it to one person who holds the master copy of the code
• I've tried this, its a lot of work for the one person
4. Some kind of shared drive or drop box (http://www.dropbox.com/)
• Getting there, but if you have to be careful, or you can overwrite each others code
5. A Version Control System
• This is what I'm talking about

So what is it?
Think about a shared drive somewhere, which holds all your code.
It also holds all the backup copies of your code, so that every time you make a change, it makes a backup (just in case you mess it up).
It also keeps track of who have been changing what so it will stop you from accidentally overwriting someone else's code if you both have been making a change to the same file.

This is a version control system.

Different types of version control
There are quite a few different types of version control: CVS, SVN, Perforce, GIT, Mercurial, Visual Source Safe and many others. See http://en.wikipedia.org/wiki/Comparison_of_revision_control_software
I'm currently using SVN, but they are all fairly similar.
(Note: those people who are familiar with distributed version control are entitled to scream at me for the previous statement.  I don't use DVCS I know they perform a similar but in a totally different way)

A few terms
See: http://betterexplained.com/articles/a-visual-guide-to-version-control/ for a good summary.
I'm using the SVN terms as it will help later

• Repository: The 'shared directory' where the code lives, usually on a hosted server somewhere
• Import: take some brand new code & put it into the repository
• Check out: Get a fresh set of the code (usually the latest version) from the repository onto your local machine
• Update: Update the code on your local machine with the latest version in the repository
• Commit: Copy the code from your local machine into the repository
• Conflict: What happens when you try to commit some code and someone else has already made a modification to it

Getting started
You will need:

1. A repository
• Since you want this to be accessible by your team all the time, its a bad idea to stick it on your machine (unless you have a spare server which you can use), so here are a few options.  They all have free plans and many have paid plans too.
• http://xp-dev.com/
• https://riouxsvn.com/
• http://projectlocker.com/
• http://unfuddle.com/
• And probably a lot more
• You only need one person to set up the repository, but you will need accounts for all your developers
2. A SVN client
• I have used Tortoise http://tortoisesvn.net/ and Rapid SVN http://www.rapidsvn.org/
• This series will look at Tortoise
• Every developer will need one of these
3. Some code (duh!)

Setting up the Repository and performing the initial import
This is a little tedious, but only need to do once, so its a good idea to have your senior/experienced developer do this.

My example will be using https://riouxsvn.com/ and http://tortoisesvn.net/, but its roughly the same for all.

1. Go to your host and set up the repository

You will have to figure this one out for yourself. But it should be simple enough.

While you are doing this, look out for an option to create 'trunk' and all the other default directories.

(I usually do this, but I'm not 100% sure I really need to)

Once you are done, look out for the URL of your SVN repository, it looks like a normal URL. You will need this later.

2. Create an (almost) empty directory to put your code into

Advise: Never start by putting 300 files into your repository on the first attempt. KISS.  If it doesn't work, its only one file.

As SVN cannot put empty directories into the repository, I always create a empty directory and put a readme.txt in there, then import this.

Note: I like to add the entire directory into source control. This gives me the option to put multiple project into one repository if I want.  I'm not sure if its a best practice, but it seems logical.

Right click on the new DIRECTORY (not the file), and import it.

When the dialog appears you will need to enter the URL of the repository which should be of the form:

https://whatever_the_SVN_repository_was/trunk/project_name

(Most will be https, though it might be http)

You need to get this first bit right, or you will hit all sorts of problems.  I always have project_name as the same as the directory, mainly for convenience.  I never have spaces or strange characters in it.  And remember to choose a suitable name too. (I have an SVN project called 'labtask', oops!)

It might ask you for your username & password, but you should soon see a result like this:

Take note of the full URL as you will need to pass this information to all your fellow developers.

At this point, I will usually delete/rename the directory away and perform the checkout (see part 2) to make sure it worked.

Continued in part 2

Mark