Source Control Your Source Control

The Why and How of Versioning Rational Team Concert Process Configurations

 

As humorously circular as it sounds, there are legitimate reasons for keeping the process configuration of a Rational Team Concert (RTC) project area in source control.

Imagine (if you have to) that you’re managing an enterprise-scale shift to RTC and have a vast, complex set of procedures that are firmly established in policy (or even law). The challenge of designing and administering a proper configuration for your needs is great. At a minimum, you’ll want to iterate through several configuration attempts (versions, I’ll call them) and test them all, and you may even hire a consultancy to facilitate the effort (like TechRev, of course). The world of RTC is populated by many needs that are more complex and nuanced then the built-in Scrum template developers so love.

A project area in Rational Team Concert is characterized by its process configuration. There are many other aspects of a project area—the data it contains in the Jazz repository, attached scripts and icons, available reports—but when we think about the biggest differences between, say, the provided Scrum and Formal Process templates, the bulk of them are matters of process configuration. If you’re developing for a scenario like the one described, it’s just as important to source control the process configuration as it is to source control the rest of the material.

 

It’s Worth the Effort

 

Rational Team Concert does not have a mechanism for versioning its own changes in the way developers need. It will record a history of changes, but there are limitations to the efficacy of that trail.

Put yourself in the shoes of a developer; you’ll want to carefully control these versions like you would versions of software or documents. You’ll want to be able to backtrack, to reference previous approaches to a solution, to check your work in retrospection, and to troubleshoot. Let’s imagine we approach the development of a process configuration for a client in just four simple sprints.

Sprint 1

  • Development of version 0.1.

Sprint 2

  • Testing of version 0.1.
  • Development of version 0.2.

Sprint 3

  • Testing of version 0.2.
  • Development of Release Candidate 1.

Sprint 4

  • Testing of Release Candidate 1.
  • Development of version 1.0.
RTC code snippet

It looks like this across 1,231 lines.

You’ll have set up a layout for the editor of a work item type in version 0.1, but prompt client feedback could result in trying a different layout for the same work item editor in version 0.2. Further testing (note that many other things could have changed too; attribute types, customization scripts, permissions) may result in the client asking for the layout to be like it was in the beginning, in version 0.1, after all. There are times when it’s much easier to retrieve the old configuration and reference or even reuse it to efficiently follow through on the change.

Here’s what that looks like in RTC’s own configuration history:

Like this man trying to measure a door, I’ve concluded there must be a better way!

man measuring door with tape measure

A Better Way

 

Keeping it Simple

 

The first step is to keep an XML file that represents the process configuration source in your source control repository (be it a separate RTC project area used for development or any repository you use). Without a clever extension, this requires a manual copy-paste from your administrative RTC client (most likely Eclipse) after each change, but really is worth it. The steps:

  1. Create a blank XML document and prepare to store it in your source control repository.
  2. Access the Process Configuration Source tab of the Project Area editor in your IDE and copy all.
  3. Paste the copied process configuration source over your XML document and deliver the document.
  4. Repeat steps 2 and 3 for every change.

If you do this for a little while, you’ll find that RTC often makes unexpected changes in unexpected places. It might add an extra blank line between configuration-data nodes, or add “final=’false’” to a node here and there (which I’ve never seen result in behavior any different than not having that attribute present at all). So, when you actually do compare a newer version of the process configuration source to an older version, you’ll be spending some extra time evaluating and skipping past these excess changes that don’t matter just to get to the real change(s) you’re looking for.

 

Staying Organized

 

pcsHierarchyTo reduce the amount of time lost to that effort, you may consider managing a directory of XML files that represent various nodes within the process configuration source. This can be done to varying levels of detail, but should be done according to the hierarchy in the complete XML.

The steps:

  1. Create the desired directory structure with XML documents appropriately placed and named. Include a document for the complete XML at the root of this tree.
  2. Access the Process Configuration Source tab of the Project Area editor in your IDE and copy all.
  3. Paste the copied process configuration source over your complete XML document at the root of the dir
    ectory tree.
  4. Return to the Process Configuration Source tab of the Project Area editor in your IDE, locate the node
    within which your changes appear, and copy the node and its content.
  5. Paste the copied content over the appropriate XML file for that node.
  6. Deliver the changed documents.
  7. Repeat steps 2-6 as necessary.

With this approach, it’s much easier to track down specific changes to specific areas of configuration, and it’s easier to get away with making more changes prior to a single delivery, since they’ll be neatly organized for future reference.

 

Being Surgically Precise

 

Both approaches described above will reduce the amount of changes that any comparison editor will identify relative to what the built in History mechanism of RTC identifies. We can reduce these changes all the way down to only the ones that really matter with a little more effort. We just have to adjust the last procedure described to include a process of comparison that identifies the exact changes that need to be recorded. The steps:

  1. Create the desired directory structure with XML documents appropriately placed and named. Include a document for the complete XML at the root of this tree and another for comparisons.
  2. Access the Process Configuration Source tab of the Project Area editor in your IDE and copy all.
  3. Paste the copied process configuration source over your for-comparison XML document at the root of the directory tree.
  4. Compare the previous complete XML with the new XML. Copy over only the changes that truly matter (from the for-comparison file to the complete XML file that represents the to-date version).
  5. Copy the node(s) that have new changes copied over (from the just-modified complete XML file) and paste them over the node-specific XML document lower in the directory tree.
  6. Deliver the changed documents.
  7. Repeat steps 2-6 as necessary.

Trust me when I say there’s an additional benefit of using this precise procedure; your knowledge of the inner workings of RTC will rapidly grow.

Alas, this procedure does not eliminate frustration entirely. The schema and editing mechanisms behind the process configuration source allow for child nodes to move around randomly, so comparison editors could easily tell you there are 20 differences between two documents when only 1 difference matters and the rest are just the same child nodes in a different order. This approach takes care of that effort proactively so that any later comparisons of versions are much easier to make, but the effort does remain.

 

Using the Right Tools

 

The biggest drain on time in these procedures is evaluating sequence-driven changes that turn out to not matter (though sequence matters sometimes and shouldn’t be ignored in those cases, which I discuss further below). Time can be significantly saved by using a comparison editor that can optionally ignore the sequence of child nodes. Using XML editing tools that enable manual sorting based on attribute values can be helpful, too.

 

What is there to be careful of?

 

This is by no means an exhaustive list of caveats, disclaimers, or warnings regarding administration of changes to an RTC Project Area. Still, it’s worth alerting readers to a couple particularly notable items to be aware of.

  • Be careful with deletions.
    • Particularly if you choose to edit the process configuration source directly (as opposed to through the Project Area editor of your IDE or the Web UI), there can be negative repercussions to deleting something that has an ID and has been used in the Jazz repository. These repercussions can slip under an administrator’s radar if XML is copied from an old version over a current version without awareness of deletions.
  • Sequence matters in some areas of the process configuration source. For example, the order that work item types display in the Web UI drop-down menu for Work Items is determined by the sequence of type nodes in the configuration-data node for the namespace “//com.ibm.team.workitem/workitemTypes”.

taskOrder1_list  =  taskOrder1_xml

 

taskOrder2_list  =   taskOrder2_xml

 

 

Efficiency through Proactivity

 

When developing a complex process configuration for RTC, taking these proactive measures can reduce huge hassles down the road for all the same reasons that developers use source control for software and documents. The process configuration source of a project area is kind of a document (XML) and kind of software (unique RTC configurations often feel that way), but is rarely thought of as something that should be managed this way. Like this woman marking measurements, I’ve concluded that the proactive preparation is entirely worth it.

woman measuring with tape measure
s2Member®
Skip to toolbar