Another Reason to Comment

Carefully commenting all updated repository objects has clear benefits. It helps trace repository changes back to the responsible configurators. It helps accomplish a sort of configuration management so that you have a rudimentary history of changes that were made to the repository.

Complicating repository configuration management is the fact that Siebel developers do not start with a blank slate. Unlike a discreet block of script, Siebel configuration might involve meeting a single requirement by changing the value of one or two properties on several pre-existing objects throughout many different projects in the repository. Careful commenting can provide information about what changes were made, and why, and when.

One drawback for commenting the Siebel repository objects is the relatively small size of the Comments attribute itself, which commonly contains information about several changes by different developers to meet more than one requirement. If each comment includes the initials of the developer, the date, the requirement number, and a description of the changes made, you will quickly run out of space. A good approach to keeping comments concise is to reference an external document, such as a detailed technical design.

With all the configuration management concerns, you might not consider another, possibly more important reason to carefully comment repository object changes. These comments can be invaluable during a repository upgrade.

During configuration, upgrading can be the last thing you want to consider, but if the project is successful, upgrading is inevitable. And the Siebel upgrade process includes a many tedious and time-consuming steps. After the repository merge, which is an automated process that transforms the repository objects from one version to the next, there are usually hundreds or thousands of conflicts that must be manually reviewed. The Reviewing Siebel Repository Object Property Conflicts process is one of the most difficult, tedious, and error-prone tasks of the entire upgrade.

The conflicts that must be manually reviewed are cases where there are three versions of the same repository object, and there is no clear path for the automated upgrade to take. Siebel provides an Attribute List View that makes the process as easy as possible, and you have a 90% chance that the automated merge has actually identified the correct "Standard Win" version. But, for the remaining 10% of the attributes, which can be literally hundreds of choices, developer comments can be the key to an informed decision.