Branch or Pin ?

It often happens that a software product is released at some point, there is ongoing development for next release, and it becomes necessary to issue a patch to the released version. There should be only minimal differences between the released version and its patch; changes that have been made in the meantime in the course of ongoing development should not appear in the patch. It would also be nice --although not essential-- if the "fix" done for the patch could automatically propagate to the ongoing version since it most likely both versions have the same flaw.

It's clear that with VSS there should be two separate projects in this situation, one for the ongoing work and the other for patches to the previously released version. It's also clear some form of VSS "share" should be used, at least to initially populate the second project, and perhaps also to form an ongoing relation between the two projects. There are two mainstream methods to do this, popularly called "pin" and "branch". While the "pin" method is the one documented and recommended by Microsoft, it has its drawbacks and the "branch" method is also a contender.

To be concrete, suppose the released version is numbered 1.1.0, ongoing work is being done on what will probably be numbered 1.2.0, and it's necessary to produce a patch version numbered 1.1.1. There should be two projects in VSS, named perhaps Foo_1_1 and Foo_1_Next.

With the "pin" method, all the files under Foo_1_1 are initially just references to files under Foo_1_Next, with what VSS calls a 'pin' specifying a particular version of the file rather than the tip. The particular version chosen should be the one that was the tip back when the product was released. The patch project may have already been created when the product was released, or you can create it retrospectively when necessary. If the ongoing project has a "label" that was created when the product was released, you can display the history of the project, highlight the line for that label, and "share" the whole ongoing project to create the patch project. All the files in the patch project will be pinned at the version corresponding to the label you selected. If there is no label, you can use the VSS Command Line to create a retrospective label given a date. Then proceed as if the label had always been there.

Developers should find each file that will be affected by the fix and "branch" it. Doing this creates a separate copy of that file in the patch project, which you can then modify as necessary to make the patch without either affecting or being affected by changes made to that file in the ongoing project. This is what Microsoft best documents and suggests.

You could also "un-pin" rather than "branch" the file. Since the single file is shared between the patch project and the ongoing project, fixes you make will automatically also appear in the ongoing project. However, since an un-pinned file immediately floats up to the tip version, all changes made to that file as part of ongoing development in either the past or the future will also appear in the patch. In other words your patch may contain more changes than you bargained for. And if your software product is not carefully modularized, the changes imported from the ongoing project may depend on changes in other files that won't be touched by the fix and so won't be un-pinned, with the result that the patch project won't even compile. Although the Microsoft documentation seems to describe this method, it never explicitly recommends doing exactly this, perhaps because of the very negative side effects that sometimes result.

The alternative method is to "share and branch" the entire ongoing project to create the patch project. This creates a separate copy of every file, so there's no chance a change made for one project can accidentally appear in the other project. This is conceptually simpler. And it's operationally simpler for developers since they never have to worry about un-pinning or branching a file. Also they never have to debug problems caused by getting only part of a change. Its biggest drawback is that it takes up more disk space since there are two copies ovf every file even though most of them are identical.

Another perceived drawback of the "branch" method is it doesn't even try to propagate fixes from the patch project into the ongoing project. But this is a false dichotomy, as the "pin" method doesn't do a very good job of propagating fixes forward either. It simply isn't true that VSS can be easily set up to propagate all fixes forward, although some VSS literature seems to suggest just that. The best way to propagate fixes forward without double-entering them is with the VSS "Merge Branches" function. This takes the changes you made for a patch line by line and attempts to insert them into the ongoing version without destroying other changes that are already in the ongoing version. If VSS can do this automatically, it will. If VSS isn't sure what to do it will toss the hard decisions back to a developer with its Visual Merge.

Some VSS users feel that in this day of very large relatively inexpensive disks, the "pin" method is no longer worth the extra developer attention it requires.