Jul 232014

A little while ago, I posted about Real Configuration Management for Requirements, but I didn’t go in to any detail about HOW it should, or could be used.  Requirements engineers/managers are not typically working with configuration management at this level on a daily basis, so I have set out a very basic flow here. First of all, you need to know that this post describes working with an open Beta release of DOORS Next Generation, and all manner of changes can occur before this functionality is ever released.

I set up an empty project as described in my previous post to work through the basic exercise shown in the image here.  One Variant, with one Version, and two Engineers working on the problem. I thought it best to start simple and find out how this might actually work for real. If I lose you in the description then come back to this diagram for reference.

2014-07-23 11.36.50-1

Setting up the Workspaces:

When the project is created it exists in a Workspace. I have referred to this as the project Trunk, and it should contain anything that is common to all versions and variants.

I took a snapshot of this workspace, and created a ‘Trunk Staging Area’ workspace, and took a snapshot here too; more about staging areas later.

I then created ‘Requirements for Variant A’ workspace (with snapshot) and a ‘Requirements for A Staging Area’ workspace with snapshot. Following on from this came Requirements for A Version 1, and a staging area. From this last staging area I then created the two engineer’s workspaces. It is here that all the work will be done.

So now I have Workspaces (all on the jazz team server, no local repositories here) set up for Variants and Versions as well as for the Engineers to work in. In the real world we would expect multiple variants and multiple versions to run concurrently as well as multiple engineers working on each. It would make sense for all work to be done in an Engineer’s workspace and then delivered to the consolidated version or variant staging area workspace.

Doing the work:

Engineer X now starts working. Change sets are created for functionality applying to just version 1, to all versions of variant A, or to all versions of all variants. Ideally each change set would belong to just one of these three categories. Each change set can also be linked to a Rational Team Concert Work Item.

I have shown in the diagram that Engineer X works on two change sets, and Engineer Y works on a third.

Delivering the work:

Having completed this section of work, Engineer X is now ready to deliver change sets 1 and 2 to the A1 Staging Area workspace, so first a snapshot was created. In an ideal world, a systems engineer, or integration engineer would PULL those changes into A1 Staging Area from the Engineers’ workspaces. Unfortunately, that is not possible, and they have to be PUSHED (from within the engineer’s workspace, but we can control who has the authority to do this). This is something that will need to be managed carefully.

Now if Engineer Y tries to deliver change set 3 to the A1 Staging Area, it is not possible until all the updates in the staging area are first incorporated in to the Engineer Y workspace. (Follow along on the diagram if this is confusing). This means that Engineer Y, or the person accepting the incoming changes to Engineer Y workspace, is taking responsibility for this merge. Change set 3 can now be delivered.

The integration engineer can now see the result of all the change sets and resolve any issues, potentially in a separate change set. Variant A, Version 1, Staging Area is now ready and reviewed and the information can work its way up the chain. Because this is a Staging Area, once any issues are resolved, all changes should be delivered to the Requirements for A Version 1 workspace. Engineers X and Y need to accept any outstanding changes before they will again be allowed to deliver. I didn’t try the option of Rebase; there is more functionality here than I want to cover in a single article.

When I look at the details for the Engineer’s workspace, I can see the change sets and their associated Rational Team Concert Work Items. The screenshot, from a previous experiment, for Engineer X workspace changes is below and you can see the link to the work items:

A1XChangeSets When I look at the same information for the Staging Area workspace, the link to Team Concert is lost, as shown below.

A1ChangeSetsI think that I really do want easy traceability from the work item to all affected workspaces. As I said at the start, this is Beta code.

Back to the diagram and you will see that I am only delivering change sets 1, 2 and 4 to the Variant A Staging Area. We are assuming that change set 3 applied to Version 1 only and not to other versions, so there is no need to deliver it up the line. There is no way to mark this as not applicable, so it will be offered every time changes are delivered.

Changes would also come up to Variant A Staging Area from A Version 2 etc, and merging would have to be handled in a similar way to that described for the two engineers’ workspaces.

Once the Variant A Staging Area is correct, the changes can be delivered to the ‘Requirements for Variant A’ workspace. Again, this should be a simple exercise as the staging area should be the only workspace delivering here.

Finally, selected changes can be delivered to the Trunk staging area. Just as for Variant A, the Trunk will have multiple areas feeding in to it (other variants), and the staging area is used to ensure that the changes are correctly reviewed and approved before being finally committed to the Project Trunk.

The image below shows the Workspaces and snapshots created for this simple exercise up to the point where change sets are created. As you can see there is a Controlling Area set for each workspace, and this defines who can edit, create snapshots, deliver changes and more.


So, what have I learned?

  • Creating all these workspaces and snapshots is tedious, but necessary all the same.
  • It is easy to forget to check which workspace you are in.
  • It is easy to start making changes before you create a change set – but you can recover, as all changes are given a change set auto-name and you can change the name and link it to a work item later.
  • You have to Push changes rather than being able to Pull them, which is not ideal, but the controlling area setting offsets this to some degree.
  • A change set is visible once pushed to the ‘Flow Target’ workspace, but at that point it loses the reference to the work item.
  • A change set gets delivered complete, or it doesn’t, so it is important to think about how far up the tree the changes will be delivered and not mix this within a change set.
  • Naming is going to be REALLY important.
  • Using the names Requirements for Variant…, or Requirements for Version… will ensure that people don’t think you already have a final version, as far as I understand it, your software team are likely to be grateful for this small concession.
  • Using a staging area workspace leaves the deliverable spaces clean
  • You can create snapshots from a number of different screens, all of which make sense, and all of which seem to work equally well.
  • Effective use of this capability is not obvious or simple. It is best to work through an architecture with your software teams (who have been doing this for years), or follow general good practice guidance. We don’t have much documented yet, this is still beta code, but there needs to be some clear basic guidance before this goes mainstream.

And what haven’t I tried?

  • Multiple, concurrent, Variants and Versions.
  • Changes that cause a Merge to take place (introduction of a conflict).
  • Comparing snapshots and workspaces.
  • Rebasing.
  • Anything even slightly tricky.

There is a lot more to be said on this, but that is for another post.

Leave a Reply

%d bloggers like this: