It’s been a while since I started this. Sorry for the delay.

Source Control is pretty easy to use when used correctly and consistently. If you start to do odd things, then it starts to twist your mind.

First up, you have a repository. This is object you are working with and where your files live happily in harmony.

The repository is divided logically into three sections. These are just names, you can replace them with what you want, but the normal nomenclature is TTB: Trunk, Tags, and Branches. I first came across this when working with Subversion but can be used in VSS, TFS and any other TLAs you can think of. 

The trunk is the working copy of your application/web-site. This should always be able to be checked out and compiled. The top of the trunk where the latest code lives is called the head.

The branches is where you perform the modifications to the source. More on this in a bit.

Tags is where you have a specified release of the repository – this is so you can roll back to a previous known working copy if something has gone arse over tits. 

Now you know what the logical structure of the repository is what do you want to do with?

If you don’t have anything in the repository you need to fill it.

The first thing you do is put a clean working copy of the source into trunk. This should have no dead files, no file with things called index.htm.old (or similar). Also when checked out it should compile and run without crashing or when mounted on the webserver, run fine. This is the bit that people don’t seem to get. If you check the file out to a clean PC with just the compiler then you should be able to build/run the app. Too many times have I branched and found the source doesn’t compile because FooWidget2000.dll cannot be found. Turns out that FooWidget2000 is availble in R:\Software on the network or is a free download from SourceForge. 

That’s not right. *Everything* needed to build the project should be under version control. Also documentation of the project should be in there too. Most large corporations use Windchill (aka Global Vault) to store their documents, but I prefer to keep the documentation with the source – closer the better. Microsoft make a repository viewer which is great for project manager to access the documentation while not having to learn the arcane commands – source control isn’t just for source any more.

Now we have everything in place it’s time to start making changes. Let’s identify a necessary change – the foo widget is displaying the wrong value for bar. You think you know what is going on so you begin to branch the source into branches – but how should you do it?

Well my way is to have the user create a folder within branches for his (or her) changes:

projects/bugatti/trunk
                /tags
                /branches/graham.reeds/id00001
                                      /id00002


 
Within that user folder you create sub-folders for each branch you make. What constitutes a branch? Well I use branches mainly for performing a bug-fix. Did you note the use of singular? 

If you are working with a specified bug tracking system (like Trac or Mantis) then you can use the assigned bug id number, or if you are working on a new piece of software then you can call it by the task you are performing. I use a mixture of the two.

You can forgo the username, but I prefer it this way. People tend to point out you can use blame (or praise) and such to see who worked on what, but I prefer the username method. If you have your name stamped on it, then you are more likely to have a sense of pride in your work. You do have a sense of pride about your craft, don’t you?

Then when you have fixed problem with bar’s value you then merge the corrections back into the trunk. Usually the merging is only done after the fixes have been peer reviewed and approved by the lead coder – you don’t want substandard code to be checked in because if the original coder leaves then it will probably be you who have to work on it – so any bad smells in the code you should flag up immeadiately. (Also don’t take the process personally – it’s tempting to nitpick if the person’s code you are reviewing grilled you over your previous submission.)

Once the source is back in the trunk then that will be tested by the testing department – you’ve tested it yourself but a decent tester will test it in half a dozen ways while programmers tend to skip through to that bit and use keyboard shortcuts the entire time, etc.

This may be the last bug to be fixed before the latest release is pushed out the door. If you are on schedule, congrats. If not, well done on getting it finished.

Now this release needs to be marked in someway. This enables you, in the future, to see what source files made up an exact release. Very useful if a bug fixed previously has crept back in over time (unit tests help here). This is the last part of the puzzle. Basically you tag (or copy as it is Subversion) a set of files to the tags branch. The tags are usually numbered, named or a combination of the two. For instance. A minor bug fixing release after version 1.0.0 could be 1.0.1, whereas an added feature could make it 1.1.0. Also if you get paid to add a special feature by the XAB Corp. you could name a version 1.1.0 (XAB) to differentiate it from the 1.1.0 (HAL) you did for the HAL Corp.

And that concludes a simple overview of how source control works.