Tracing Source Code Changes to Requirements, Task and Bugs

Disciplined source code changes associated with valid tasks increase stability, consistency, transparency and traceability in collaborative software development environments.

When a managed repository is used (for example: Git, SVN, Mercurial), codebeamer provides links to show the associations between a Task-ID and SCM commits by default. This level of traceability can also be explicitly configured for external repositories. The script that enables the Task-Commit associations is called SCMLoop. See Installing SCM Loop.

In codebeamer 5.5, commits can be edited. For further information, see Tracing Source Code Changes to Requirements, Task and Bugs, Version Control: Subversion (SVN), Git, Mercurial and CVS.

When the SCMLoop script is enabled, it intercepts the source code commits and invokes codebeamer to associate the commits with a codebeamer tracker item (for example: a task or a bug).

When the SCMLoop is installed, either by default with a managed repository, or explicitly, use the following syntax in the commit messages when committing changes to your SCM:

#1234 Fixed an NPE

Where 1234 is the tracker item which the commit is to associate with. Enter, for example:

#1234, #3456,#4533 Fixed memory leak

Where 1234, 3456 and 4533 are the tracker items which the commit is to associate with. A space between the (,) and (#) is optional.

Entering, for example:

Fixed an NPE to resolve [BUG:1234]

does NOT associate the commit with any tracker item, but

#1234 Fixed an NPE. See [BUG:5678]

associates with tracker item 1234, and the text will have a Wiki link to 5678 as well.

The commit syntax with # is configurable by adding the following regular expression to the System Admin ► Application Configuration ► "scc" node:

"task_expression" : "#(([1-9][0-9]{3,9})((,|\s+)[1-9][0-9]{3,9})*)(?:\z|[\s.,;:)\-]+)",

How Does a Task-Based Process Work?

When SCMLoop is installed and enabled (see Installing SCM Loop, commits in the SCM commit action require a tracker item (task, bug etc.) ID entered either from an IDE or from the SCM command line interface, together with the commit command.

codebeamer records the file name, file version, user name, and date/time in the codebeamer database and associates it with the tracker item having the specified ID. There is also a mechanism for browsing the SCM repository using codebeamer's SCM Web interface and see the tasks associated to each file.

Enabling a Task-Based Process for a Project

When SCMLoop is installed, the codebeamer server receives notifications on SCM commit actions. This can be enforced for any project by enabling the task-based process. When this enforcement is active, each commit action must be associated with a valid task. The advantage of a task-based commit process is the automated association between software changes (commits) and tracker items (task assignments, change request, bugs etc.).

Enabling a Task-Based Process

To enable a task-based process:

1. Open a project,
2. Click on Admin tab,
3. Click on SCM Settings,
4. Having the SCM system already selected, click on Set,
5. Select the Allow checkins/commits only with valid CodeBeamer Issue IDs checkbox,
6. Select the Allow checkins/commits only for members with SCM-Commit permission checkbox,
7. Click on [Save].
   
   

Figure: Configuring task-based commit, and user commit access on the repository.

Committing Actions from IDEs

Developers can associate commit actions from their IDEs, from the CVS or Subversion command line interface or from other clients e.g. WinCVS or Tortoise SVN. codebeamer provides deep integration with IBM Websphere Studio and with the Eclipse IDE, enabling developers to commit changes from their IDEs with associated tasks. From the IDE, one or more files can be associated with one or more items (n:n relationship) on commit actions.

Figure: Example Commit with Task ID from the CVS Command Line Interface

Accessing the SCM Commit History

During project creation the SCM commit history is read from the repository. The history data is updated continuously by the Periodic Process Timer. For more information, see Global CodeBeamer Settings: Working Calendar, Periodic Process Timer.

The following SCM commit history chart can be sorted by date, author, comment text or file.

Figure: SCM Commit History Chart

Accessing SCM Modules Associated with Tracker Items

In the tracker items summary viewer, the database icon is displayed when an item has associated SCM commits. In the following figure, the tasks or issues associated with commits (code changes) are shown with the SCM icon.

Figure: Tracker Issue Summary List

To view details on commit history click on an issue. The following figure shows a single Tracker Item, with the SCM Commits tab selected, to show the file changes associated with the Bug.

Figure: A Tracker Items' SCM Commits

Reassign Commits to Tasks

A privileged project administrator or the submitter of a Commit to a SCM Repository, can now edit commits listed in SCM Repository ► Browse Commits:

Figure: A Commit in an SCM Repository

By clicking on [Edit] in the popup menu of a commit, an editor screen opens which allows to change the comment and re-assign the commit to different codebeamer Tasks:

Figure: Edit the Commit in the SCM Repository

Changing the commit information in codebeamer, not in the underlying SCM Repository.

If the SCM Repository Synchronization has been set to Checkout regularly all files from repository, or the Synchronize and reparse the project now is executed manually, any changes made here will be overwritten with the old values stored in the repository.