Thursday, June 26, 2003

Beyond CheckOut and CheckIn

Many people use only a small portion of the features of the version control system.  If you use little more than checkout and checkin, you might actually be in the majority.  A Vault user recently asked me to explain why anyone would use things like Share, Branch, Label, Cloak, and Merge Branch Into Trunk.  I had fun writing my response, so I thought I would re-post it here.  Beware, this writeup doesn't even attempt to be objective about which version control product is most neato. :-)

The "more advanced" features exist for teams and projects which are, er, more advanced.  The bigger your team, the bigger your company, the more stuff you have going on, then the more powerful you want your SCM tool to be.

Even still,  I've run across teams of significant size who prefer to use only the basics.  The truth is that concurrent development is hard. Good SCM tools make it easier, but some people prefer to adopt processes which prevent complexity instead of using tools which help manage complexity.

But for those who dare, good version control systems offer several ways to maintain your sanity even while lots of things are going on at one time.

Label

The most painless feature on your list is Label. Labels are conceptually very simple and are used by most teams.  A label is used to mark a specific version of a file or a group of files.  It is typical to apply a label when a project milestone is reached. A label is often applied when an important build is made, thus making it easier to retrieve the exact source code which corresponds to that build. In other SCM tools, labels are sometimes called "tags".

As I've mentioned before, Vault's labels are a little different from SourceSafe's labels because they appear as just another folder in the repository hierarchy.  A label is used to remember a snapshot of time in the history of your tree, so Vault presents that snapshot as a tree.  In SourceSafe, a label is merely a string which is associated with a set of versions of items.  The use cases remain the same.

Suppose you've been working for months to deliver a beta to your customers.  When you finally reach completion, you build your beta release.  You want to remember exactly what the state of your repository was at the moment you reached beta, so you create a Label.  You can later fetch the files from that Label and you will get the same versions you used to build your beta release.

Cloak

Another rather painless feature on your list is Cloak.  This one is actually even simpler.  Cloak allows you to hide folders you don't care about. The folder is still there, but you no longer have to deal with it.  For example, assume you have a big folder hierarchy.  Three levels down, your marketing people placed a folder containing a whole bunch of enormous TIFF images.  Developers don't want to be retrieving this stuff every time they do a get-latest operation.  Luckily they can just cloak that folder and Vault will pretend it's not there.  Cloak is a personal feature.  When you cloak a folder, you hide it from yourself, but others can still see it.

Share

Taking a step up the stairway of complexity we come to Share.  This feature allows a folder or file to appear in multiple places in the repository.  For you Unix-heads out there, Share is somewhat like a file system link.

For example, suppose your team's projects are in $/blue and another team in your company stores their work in $/red.  They have a library in $/red/turboLib that you want to use, but you don't want to constantly be fetching everything else in $/red.  So, you Share $/red and make it appear as $/blue/red/shares/turboLib. Now, the following two repository paths actually point to the same folder:

$/red/turboLib
$/blue/red/shares/turboLib

Any change to one of these folders will automatically appear in the other.  They are not copies of each other. Rather, there is only one instance of the folder, and it simply shows up in two different places.

Note that Vault's share command works considerably better than SourceSafe because folders can be shared, not just files.  When you share a folder in SourceSafe, it just recursively shares every folder inside.  If this example were done in SourceSafe, then $/blue/red/shares/turboLib would simply be a set of new folders which contain a bunch of files which are individually shared with their counterparts back in $/red/...  However, the folders themselves are distinct.  After the Share is created, if you add a file to $/red/turboLib, that new file will not automatically appear in $/blue/red/shares/turboLib. With Vault, the added file does appear, because the folders themselves are shared, not just the files.

Pin

You didn't ask about Pin, but it deserves to be mentioned here.  Pin is handy when you have shared something but you want to freeze it.  Let's say that you've been happily benefiting from the excellent efforts of the red team and you're very happy with how turboLib is working out for your project.  Every time they checkin a change to turboLib, it magically becomes part of your tree as well.  Suddenly one Friday, the manager of the red team decides that the fridge in their building will from now on be stocked with free beer for all the programmers.  Shortly thereafter, the quality of turboLib starts going down.  You are no longer quite as happy with the Share you established.

So, you bring up the Show History window and Pin $/blue/red/shares/turboLib to the version which existed on that fateful Friday.  The red team can continue their "work" in $/red/turboLib, but your side of the share link will no longer automatically get their changes.  It has been frozen at a Friday in the past.  If you later Unpin that folder, the Share will become alive again.  As long as your folder is pinned, you can't make any changes in it.

Branch

This brings us to the topic of Branching.  This is the most advanced of the features you mentioned.  Suppose you have a folder in which development is going on, but you want to start a second development effort using that same folder.  You want the two efforts to be separate, even if you eventually want them to be one again. What you want is a branch.

Returning once again to my Share example, let's assume that after several weeks of the party life, the red team doesn't seem to be returning to normal.  Pin has shielded you from their rather questionable checkins to turboLib, but now you need more.  You need bugfixes in turboLib.  It's time to take matters into your own hands and start maintaining your own version of turboLib.  It's time to Branch.

You can branch at any version you like.  In this case, you want to branch back on that freaky Friday when the red team began its decline. Those versions, the same ones you've held pinned for the last several weeks, will be the initial contents of your branch, which you create at $/blue/red/forks/turboLib.

There continues to be a relationship between $/blue/red/forks/turboLib and $/red/turboLib. They share all their history prior to that Friday.  But after that Friday they diverge. Changes to one folder do not appear in the other.

Merge Branches

Now let's say that the manager of the red team leaves and the new manager is horrified to find beer in the fridge.  The beer is removed and the red team gradually regains its capacity for consecutive thought.  Suddenly the red and blue versions of turboLib might seem a little too detached.  The blue team has made changes which the newly coherent red team finds desirable.  Similarly the red team is now beginning to improve turboLib again, leading the blue team to become interested in their new changes as well.

What these two teams need is the ability to migrate changes back and forth.  This feature can go by different names.  Vault and SourceSafe call it "Merge Branches".  The basic idea is that the user can review changes to either folder and choose to apply those changes to the other folder.  The SCM tool tries to make this process as painless as possible.

Different SCM tools handle branch merging in different ways.  Suffice it to say that the topic is extremely complex.  A truly powerful implementation can require years of development.

The branch merging support in Vault 1.0 is not as powerful as the more mature players in the SCM market.  For example, Vault 1.0 can merge in only one direction, from the branch back into its trunk.  In my example, Vault 1.0 would only be able to merge from the blue version of turboLib back into the red version.  But we have clear plans and designs to keep improving our branch merging in future releases.

And even though Vault 1.0's branch merging is not the most powerful implementation, it may be one of the easiest to use.  We implemented this feature as a wizard which walks the user through the process step by step.  Our goal was to make branching less "scary", and we plan to maintain that value as the feature becomes more powerful later.