Change Management within a View

This topic describes best practices for managing changes within a view.

Undoubtedly, your most active views will be activity and sandbox views. But, unless you’ve figured out how to write defect-free software, you’ll also need to make changes to release views. And, although we don’t recommend it as a general practice, for small changes, it often makes sense to perform updates directly in the main view. In all of these cases, your team has several choices for the process by which they perform updates.

The appropriate process depends on the size of your development team (which affects the probability of conflicts) and the level of detail with which you need to track changes. So, let’s first review the ways in which changes are documented, tracked, and queried in StarTeam:

• Each new artifact revision can receive a revision comment where the user can document why the revision was created. Projects can be configured to require the revision comment for files.

• An artifact’s revisions can be reviewed and compared in the History tab of the StarTeam Cross-Platform Client. Historic revisions include the revision comment, modifying user, modification timestamp, version number, and all other properties as of that revision. The StarTeam Cross-Platform Client allows you to customize what properties are shown in the History tab and to compare file content changes in a dedicated File Compare pane.

• Unless audit generation has been disabled for the configuration, an audit record is generated for both revision-generating changes and other updates such as moving an artifact to a new folder or attaching an artifact to a label. You can query audit records in the StarTeam Cross-Platform Client’s Audit tab. The length of time that audit records are retained is configurable via the Server Administration tool. We recommend that you always enable audit generation and retain records for at least 90 days.

• Through process items or explicit actions, links can be used to connect change items such as CRs and tasks to files that were added and modified on their behalf. Links generated via process items are pinned to the specific artifact revisions involved at both ends. You can view an artifact’s links in the StarTeam Cross-Platform Client’s Link tab. To navigate to a linked item, right-click the item and choose Select Linked Item from the shortcut menu.

• Artifacts can be attached to revision and view labels so that revisions related to a common task or milestone are easily identified. (StarTeam can automatically attach new and modified files to a revision label at add/check-in time.) Choose Select > By Label to see the artifacts attached to a label. The labels to which each artifact revision is attached can be seen via the StarTeam Cross-Platform Client’s Label tab.

• TheStarTeam Cross-Platform Client offers several text-based reports and graphical charts for reporting on historic revisions, links, audit records, and other information. You can also create custom report templates that can be saved and reused.

• All of the change information described above can be accessed via the StarTeam SDK. If none of the built in reporting mechanisms are sufficient for your needs, you can build custom reporting tools or applications. Custom tools can even be centrally stored and automatically downloaded to StarTeam Cross-Platform Client users, where they can be activated via the toolbar.

• The Datamart product allows information from a StarTeam project, configuration, or multiple configurations to be extracted and loaded into a relational database, which can be queried and analyzed through reporting and business information tools.

Now that we’ve looked at the primary means by which you can report on changes within a view, let’s look at ways in which you can manage change. We’ll do this by examining three scenarios in increasing order of “formality”.

Scenario 1: Working in a Small Team

If you’re working on a project managed by a small team, you may not need much formal change management. Furthermore, if code modules are clearly assigned to individuals, or if you can just lean out your office door and yell, “Hey, I’m working on the report module”, then the possibility for conflicts may be very low . In this case, your change process may be very simple:

Maintain a set of local working folders where you keep the latest files for each view.

Before you begin a new development task, get your working folders up-to-date by checking out any “Missing” or “Out of Date” files.

As you modify files in your working folders, you’ll see their status in the File tab become Modified. New files will appear as Not in View because they have not been added to the view yet. New folders will appear as Not in View in the Folder tab. If you enable Show Not-In-View Folders in the Folder Tree menu, you’ll see not-in-view folders in the folder tree regardless of which tab is selected. The folder tree always shows Current folders and those Missing from your workspace.

When you’re ready to check-in, refresh your window (if you don’t have automatic refresh turned on) to see if another developer added or modified anything that may affect you. Check-out any new Missing or Out of Date files.

If another developer checked in a file that you modified locally, its status will become Merge. The best way to resolve the merge conflict is to check out the file and answer Yes to the Do you want to merge prompt. This will launch the File Compare Merge tool. If there are no conflicts, the merge tool usually just saves the merged result file over your existing work file. Otherwise, you may be prompted to review and tweak the result file before continuing. Once saved, the file’s status will change to Modified.

When you have only Not in View and Modified files, to do a build, run unit tests, and/or do any other validation steps your team requires.

Finally, commit your changes to the view. You can select all of the new (Not in View) and modified files and check them all in at once. If you add/check-in multiple files in a single step, they are committed as an atomic transaction. Moreover, file content is pushed to the server “outside” of transaction state in a restartable manner. So, if you cancel a large multi-file add/check-in operation before it commits, you can restart it by just doing it again, only files that didn’t make it in the first attempt will be sent to the StarTeam Server. The commit happens at the end only when all content has arrived using a single transaction.

And that’s it. You get revision history and audit records automatically. This process doesn’t fool with labels, and you don’t get process item links either. But it might be all that your organization needs.

Scenario 2: Preventing Merge Conflicts

As your team size grows, the problem you may find with the previous scenario is encountering too many unexpected merge conflicts. Your team may want everyone to know when you’re about to make changes to a file before you actually do so. To better communicate intent and reduce the likelihood of merge conflicts, you can amend the process outlined in the previous scenario as follows:

In the Personal Options dialog box, select the options Mark unlocked working files as read-only and Clear file locks on check-in.

When you want to edit a file, lock it via the StarTeam Cross-Platform Client first.

When you check-in modified files, the tools will automatically unlock them for you (in the same transaction in which the changes are committed).

This process both informs team members of who is working on what, and it minimizes merge conflicts. Note that your team can require this process by setting the project-level options Require exclusive lock when files are checked-in and Mark unlocked files read-only. It’s up to you and your team to decide if you want this level of enforcement.

Scenario 3: Using Process Items

The next step in a more formal intra-view change management practice is to use process items so that all file modifications are linked to an appropriate change item. You can enforce the use of process items at the project level using the Process Rules options. These options let you:

• Require the selection of a process item when new files are added or modified files are checked in.
• Select which item types are eligible as process items. Your choices are change requests, tasks, and requirements.
• Specify whether or not the Status of each item type will be considered in order to be used as a process item and which status values are permitted. For example, you can specify that change requests must have a status of Open, but tasks can be used regardless of status.

When you enforce process items, existing files cannot be modified and new files cannot be added until an eligible process item is selected. Consequently, new and modified files are automatically linked to the selected process item, enhancing the context information of these changes. Moreover, the links are created in the same atomic transaction in which the file updates are performed.