Any code you write should be submitted within 24 hours. If you have made changes to code on any of your projects which has not been submitted in the last day then you need to read this.

Back to Basics

Let’s recap on why it is importance to check code in frequently:

·        Your changes are safe – so they won’t be lost if your laptop breaks.

·        Other people can take over your work – if you have to go on emergency leave.

·        You can rollback changesets – if you want to revert your recent changes.

·        You can identify bugs quicker – isolating a bug to a small change makes it easier to fix.

·        Each changeset describes the code – it is much easier for someone to work out what a piece of code is designed to do if it was submitted in a small self-contained changeset.

I hope we all agree on most (if not all) of these points, otherwise you question why you are using version control at all.

Submitting Unfinished Code

One of the golden rules of version control is that you don’t submit unfinished code. You can work in your private workspace to develop and test your code in isolation. When you are finished you submit your changes to the Development Stream.

So if it takes a week to develop and test my changes, I can only submit my changes when it is finished.

Wait. Let’s rephrase that slightly.

So if it takes a week to develop and test my changes, I can only submit my changes to the development stream when it is finished.

You can therefore create a feature stream for your changes. In the feature stream you can submit as often as you want. When you have finished your changes you can merge them all back into the development stream.

Feature Streams are Easy

I bet there are some people who stopped reading this as soon as I mentioned the term ‘feature stream’ – development is complicated enough without having feature streams. But let’s break this down and look at why feature streams are perceived as complicated:

·        I’m only going to be working on this change for a week. I can’t be bothered setting up a new stream and everything else.

·        I don’t want the complexity of merging changes to and from the feature stream.

Now let’s look at these 2 points in turn.

Create a Feature Stream in 10 Seconds

In the PureCM GUI go to the Repository View. In the folder containing the development stream(s) for this project create a new stream folder and call it ‘Stephen’s Features’.

Now right-click the development stream and select ‘Create Stream From’. Call the stream ‘Feature A’ and put it in the new stream folder.

That is it! For the next feature you won’t even need to do the first step.

You can now right-click a workspace for the development stream and select ‘All Tasks | Rebase Workspace’. This will change your workspace to use your new feature stream. Since the files in the feature stream are currently identical to the files in the development stream the rebase will take no time at all.

Automate Merging to a Feature Stream

I lied. It might take 20 seconds to create your first feature stream.

There is another step you should perform after creating the feature stream folder. Right-click the ‘Stephen’s Features’ folder, select Properties and go to the ‘Merge Paths’ page. Uncheck the ‘Inherit Merge Path properties from parent’ checkbox.

Note that this functionality is only available with the Professional Edition. You can use feature streams in the Standard Edition but merging into the feature stream will have to be a manual process. If you are using the Professional Edition then you need to enable the ‘Professional Policies | General | Merge Path Administration’ and ‘Professional Policies | General | Enable Merge Paths’ policies if you have not already done so.

OK. I know this dialog can look a bit scary. But just go with me and select the checkboxes as shown above. What this mean is that whenever a changeset is submitted in the development stream it will be applied to the feature stream.

Feature Streams in Action

Now the feature streams are all setup, let’s see them in action. In the Repository View delete the old ‘Feature A’ stream (because it was created before we updated the stream folder permissions). Create a ‘Feature B’ stream and rebase your workspace to it.

Now pretend someone else is working on the development stream by creating a workspace for the development stream and submitting a simple changeset. If you now go back to the Feature B workspace you will see that the workspace is out of date and the Submitted Changesets shows the new changeset as outstanding.

Look familiar? The workspace is exactly the same as if you had been working in the development stream. You just need to update your workspace to get the new changes. So as you can see, in the general case where the files you are working on have not been changed by someone else, working in a feature stream is no different to working in the development stream.

Let’s see what happens if another developer changes a file which you have already changed in the feature stream...

Submit a change in the workspace for the feature stream. Remember that the big advantage with feature streams is that the change is not pushed to the server until you say. So this submit could just be a checkpoint of unfinished work.

Now go to the development workspace and submit a change to the same file. You will see that this submit succeeds. This is correct because changes in the feature stream should have no impact on developers working in the development stream.

If you look at the feature stream in the Repository View you will see that it has Pending Merges.

This is telling you that a change was submitted in the development stream which conflicts with changes in the feature stream. Right-click the pending merge changeset and select ‘Merge Change’. This will launch the Resolve Tool – exactly the same as if you had done an update to latest in the development workspace which caused conflicts.

In other words, the only difference between working in the feature stream and working in the development stream is that you need to merge any changesets with conflicts.

You do not even have to go to the Repository View to view your Pending Merges. Within a workspace you can use the menu ‘Workspace | Show Server Files Tab’ to launch a window showing the Pending Merges.

The final piece of the jigsaw is how the submitted changes in the feature stream are pushed to the development stream. Let’s demonstrate this by submitting another changeset in the feature stream workspace. So we now have 2 changes submitted in the feature stream and we want to merge them back to the development stream as a single changeset.

Go back to the Repository View, right-click the development stream and select ‘Merge Changes’. Select the feature stream as the source stream. You will see that only the changesets submitted in the feature stream are listed. Check all of the changesets and press Finish. Don’t choose for PureCM to automatically merge the changesets, because this will merge each changeset individually.

PureCM will then launch the Resolve Tool showing you all of the changes you have made and allowing you to change the description. When you press ‘Save’ the changeset is merged back into the development stream.

So as you can see. The process of pushing the feature stream changes back to the development stream is similar to the process of submitting a changeset. The only difference is that you have the slight overhead of using the Merge Wizard.

Remember that there cannot be conflicts when merging your changes back into the development stream, because you have already merged all the development stream changes into your feature stream. The merge will always be trivial.

Are Feature Streams Worth It?

As a developer, if you value the ability to checkpoint your code often so you can revert back to it, then yes I think the small overhead with feature streams will be well worth while.

If not then you might decide that you are happy working without them and only submitting every week or so. But if the day comes when you end up loosing a week’s work because your laptop breaks or your release is late because a developers had to take emergency leave then you might wish that you had been using feature streams.

Wish List

PureCM handles features streams well, but there is plenty of room for improvement. Thankfully most (if not all) of these new features will make it into the 2010/1 release (April 2010).

·        Simplify pushing the changes back into the development stream. There should be a toolbar button on the workspace which merges all the changes back into the development stream.

·        Automatically resolve pending merges when updating the feature stream workspace. This functionality would then be identical to when working on the development stream.

·        Distinguish between feature streams and other streams. For example, when displaying the submitted changesets the release streams are very relevant while the feature streams are not.

The first blog in the new year, so first of all my best wishes for 2009! Let me use this fresh start to give you a summarised outlook on PureCM 2009-1, our next major release coming with some rather big changes. So now you might expect a huge list with all the main features, but allow me to make a small detour before getting there...

If you look at your file system, your data is organised in folders and files. Typically, the highest level folder separates your projects. This is also the approach used by most source control tools such as VSS, SVN or Perforce to structure data in their database. You make changes to a copy of your files or folders, and they get sent back to the database and stored as a new revision.

PureCM uses an additional high level object that includes the files and folders of a project: streams. Streams have two major advantages. First, they remember the relationship between each other, making merging (and merge tracking!) much more transparent. Second, they allow for so called “cheap” snapshots, i.e. branching without making file copies. This allows you to setup your configuration for parallel development, increasing productivity.

Depending on the complexity of your shop, you can create as many (or little) streams as you wish to separate projects, teams, development from maintenance etc... All projects –organised in streams – are stored in the PureCM repository database to keep it safe. You can find some examples later in this blog [anchor].

As a development manager, you need to have all information about your projects at hand. You want to know which changes have gone into a project, which bugfixes need to be merged, or where you are including a specific version of a shared library. So the first big change in PureCM 2009-1 is its repository-centric GUI. To structure the large amount of information present in a repository, the new task-specific views filter the information you need to speed up navigation.

As a developer, getting your own sandbox to work on a task in isolation is one of the main views you need, so this is what you get with PureCM 2009-1: the project files and folders, as well as your current changes and all submitted changes to the stream your current workspace is based on. You can thus organise your own changes into changesets, and track the submitted changes from your colleagues you need to integrate.

Note the navigation bar just below the menu bar, which gives you quick access to all the task-specific views. Say you are required to switch to an urgent bugfix and would like to get an overview of your workspaces in this repository, just click on “Workspaces” and select or create the appropriate one.

Likewise, go to the “Streams” view to browse the server, branch your project, and create a release or a stable baseline. You can find out more details about the advantages of the task-specific views in this blog.

Once you have finished a task and would like to move your workspace to the next project or baseline, another new feature in 2009-1 helps you to do this easily: Workspace Rebasing. This feature automatically populates your workspace with the content of any stream you select. No need to delete the existing workspace and create a new one anymore.

Talking of streams actually brings us back to the above discussion about the project structure of a PureCM repository. According to the complexity of your projects, your repository might resemble one of the following (stylised) examples:

In example A, the streams remain typically the same and changes get merged (or promoted) from development to QA to Production. Example B shows a mainline development example with release snapshots, while example C extends the former to a multi-product setup with shared libraries.

You can immediately see that you can use stream folders to organise your streams (or codelines). In this way, you can define permissions on the folder level that get inherited by the streams. This would allow you to define release streams as read only or editable, i.e. used as labels or maintenance branches. In other words, any stream will evolve in isolation or stay static after creation, depending on the stream (folder) policy.

With the new 2009-1 release, you will be able to define Merge Paths between any two streams to track and merge changes in real time. Say you know that you want to keep track of differences between “Feature A” and “Mainline”. Create a Merge Path and you will be able to see at any time, which changes are present in one stream but not in the other, just as in the screenshot below.

This information is also visible in the "Streams" view to highlight pending merges in your stream hierarchy. After merging, the changes get moved to the “Merged changesets” node to track them. Note that all that happens directly on the server, without the need to create a workspace for merging (but you could of course choose to do so as an option).

Using merge paths, you will even be able to define automatic merges! This basically means that any change submitted to the base stream gets instantly merged into the destination stream. In case of conflicts, PureCM automatically moves the change to “Pending Changesets” to allow you to resolve the conflict manually. Of course, one can still choose to make a one-off merge directly on the changeset without defining a merge path.

The essence of the PureCM 2009-1 release is its focus on making work with multiple projects easier. It will not just be easier to work with parallel configurations using Merge Paths and Workspace Rebasing, but also to get the relevant information with the new task-specific views. But before I forget: PureCM obviously gives you more than just that, including advantages like:-

• Eclipse and Visual Studio integration
• Proxy Server for distributed teams
• CruiseControl.NET and FinalBuilder integration
• Shared libraries between projects (called “Components” in PureCM)
• Integrated issue management
• .NET/Java APIs

We will shortly publish the PureCM 2009-1 beta2, which I will certainly announce in this blog. I look forward to getting your feedback once you have been able to play around with it!

Following on from Tim Rutter’s article ‘Better Merging – Part 1’, we have looked at how to improve the merging capability of the tool even further by introducing Merge Paths and a Merging perspective for the 2009-1 release (see Stephen Worthington’s blog on perspectives – ‘PureCM gets a complete makeover’). This is especially useful if you have a staging hierarchy, eg. Development, QA, Release. In such a situation, pushing changes to the next level becomes very transparent. There are many benefits from introducing these merging features, here are the key ones:

Centralized location

A new Merging Perspective provides a central location where users can easily see which changesets have been merged between streams as well being able to carry out required merges. From here users can create new merge paths and see all existing ones. A merge path consists of 4 nodes:

Merged Changesets – Here you can see which changes have been merged from the source stream to the destination stream.

Pending Changesets – Changes that have failed the quick merge process will end up here, allowing you to carry out a full merge, resolving any conflicts (see "Better Merging – Part 1" blog). Changesets can be moved here directly, from ‘Unchanged Changesets’ or all changesets could be moved here for certain types of merge paths. We’re going to introduce an option that would force all changes to become pending for the path. So for example if you have created a child stream and you know you want all the changes that will be submitted to the parent then it makes sense to make all the changesets pending.

Unmerged Changesets – All changes that have been submitted to the source stream, but have not yet been merged to the destination stream are shown here, with functionality to carry out the merge, move to pending, or move to excluded.

Excluded Changesets – When a changeset should not be merged to the destination stream, it can be placed here, helping other users to avoid performing unwanted merges.

Creating the Merge Path..

The display name can be edited to provide a friendly name.

Automatic Merging

Automatic merging optionally takes place when changes are submitted to a stream. So for example, if multiple streams exist that are based on one ‘main’ stream, and it is important that these streams are kept up to date with Main, then a merge path could be created for each of these, with the option to ‘automatically  merge’ switched on (ie Main -> Stream1, Main -> Stream2 etc). This would result in the submitted changes being quick merged to the other streams at the time of the submit. If the quick merge fails, due to conflicts, the changesets would then appear under the Merge Path node as a pending change.

When working with automatic merging, Continuous Integration becomes a very useful practice to control code quality, so look out for a future blog on Continuous Integration...

Further usability improvements

We’re well underway in the development of these new features but have plans for more usability features:

Allowing one off merges to take place from the Merge perspective is an idea we are considering – so rather than having to navigate to a stream, or Workspace, you should be able to use the Merging perspective to do any merge. A ‘My Pending Merges’ node will be useful for developers who have submitted a change to a stream and then need to merge to other streams. This will list only their changesets that need merging. An ‘All Pending Merges’ node will be useful for managers or administrators responsible for overall merging to quickly see what needs merging.

We’re always open to suggestions or ideas so if you have any regarding merge paths, or merging in general, please let us know.

One of the great strengths of PureCM has always been it's support for parallel development. PureCM's merge functionality allows you to keep track of your changesets and which streams they have been submitted against while making it easy for you to merge these changes into other streams as desired. Now we are looking at making merging even more powerful and simple, but let's first take a look at how merging works today.

Merging Today

The original merge process required you to own a workspace for the stream you are merging into. This gives you a number of benefits such as the ability to easily test each change before submitting it to the server. This is shown as (B) in the lower half of the picture below.

However this process can be time consuming and is hard for manager who may not always have a workspace for each stream. This led to a solution that allows users to quickly merge changes between similar streams, which we called “quick merge”. This allows you to merge changes directly on the server removing the need for a workspace in these situations (A in the picture above).

So far, quick merge will only merge changes where there is no possibility of a conflict. This works well for merging last minute fixes into a release stream or early on in the development cycle when not much has changed in the new development stream but we felt there was a need to improve on this restriction.

Moving Forward

The next stage in this evolution is to allow you to resolve conflicts as part of quick merge without the need for a workspace. This will simply launch the familiar PureCM resolve tool when quick merge finds a conflict.

Combining this new functionality with automated test and build processes (such as PureCM's Cruise Control plug-in) provides a fast and simple way to keep your streams up to date while giving you the security that any errors are picked up immediately so you can assign someone to look at it.

This new advancement to quick merge opens up a realm of possible future features for the tool to help speed up your development process through merging. One example of this is the creation of automatic merge paths to control the flow of your changes through your development streams. Plenty of reasons to look forward to the 2009-1 release – and keep your eyes open for future blogs for information about where we go from here!