June 2, 2008

Labels vs Snapshots

Surround SCM
Surround SCM supports the use of labels and snapshot branches. Depending on the situation each can be used to achieve successful source code change management. Since both features can achieve similar results, deciding when to use each can become confusing.

What is a label?

The Surround SCM User Guide states that "Labels mark a version of a file or repository". So, labels allow you to retrieve a past version of a file that was marked for a specific reason. Some reasons to use labels include marking a release, a build, or a defect fix. The benefit of using labels is that you can use a more logical approach for marking file versions. For example, instead of having to remember which file version was associated with a release, you can look for the "Release XYZ" label. If you get the file based on that label, you will get the revision associated with Release XYZ. It is important to note that labels in Surround SCM only capture file content. If you perform a get based on the "Release XYZ" label, the file will include only the content that was in the file when you applied the label. You are not guaranteed that the file name will be the same (if the file was renamed after the label) or that the file will be placed in the same directory (if the file was moved after the label). Because of this, labels are not the best approach to have guaranteed repeatable builds or releases. If you have to do an old build or release and your old build scripts expect a file to have a certain name or be in a specific directory, the build may fail if you use labels.

What is a snapshot branch?

A snapshot branch is defined in the Surround SCM User Guide as a static branch. Snapshot branches cannot be modified in any way. Snapshot branch history includes the full history of a file in the parent branch. You can view the actions performed on a file before the branch was created and get, view, or diff files from the parent branch. Like labels, snapshot branches capture file content. The content can be that as of the time of when the branch is created, a specific point in time, content mapped to a label, or even content mapped to the latest version associated with a state in the workflow. Note that if you create the snapshot branch based on a label or the latest version mapped to a state in the workflow, the branch only contains the files that meet that criteria. Unlike labels, snapshot branches capture the file name and directory structure. Because of this, snapshot branches are the way to go in order to have guaranteed repeatable builds. Your build scripts for those old builds will be able to find all the files regardless of renaming or moving files.

When should I use a label?

Labels are ideal if you want to mark a version of a file or files for future reference and there isn't a need or requirement to preserve the original file name or location. You could use labels on a group of files to indicate a bug fix or a change request.

When should I use a snapshot?

Use snapshots when you want to capture a milestone, especially those that you may need to come back to in the future. If you may need to recreate an old build or release, snapshot branches are the way to go.