Guideline: Enhanced Defect Tracking with RTC
This guideline describes the enhanced capabilities supported by the attached RTC (Rational Team Concert) process template.
Relationships
Related Elements
Main Description

Note: This RTC process template is an example and delivered as is.

Overview

The STG Defect is an RTC Work Item Type that provides additional capabilities and customizations that are not available out of the box. It helps ensure convergence and consistency across multiple RTC projects and allows problems to be shared across multiple RTC repositories. Note that the original Scrum Defect Work Item Type has been renamed as Issue.

In support of the STD Defect Work Item Type, a Change Record Work Item Type has been introduced, with the following characteristics:

  • Only exists as a child work item or either STG Defect or Task WIs
  • Tracks changes at the Internal Release / Stream Level
  • Can be used to provide process enforcement
Key Terms and Concepts
  • Server-name & port - Used to connect to the "RTC Repository" which contains your RTC project.
  • Project - Logical collection of components and releases and authorized team members for a development product
  • Category / 'Filed Against' - project sub-areas, sub-components
  • Release / 'Found In' - Reported, External releases where defect found
  • Change Record:
    • Internal release - Logical grouping of 1 or more streams.
    • Stream - Jazz SCM stream
Relationships

The following diagram presents an overview of the relationships between the main RTC elements:

 

Installation Instructions

RTC Server Extensions

The following files are used during the server installation:

  1. If your server has the old "jazz" context root (server_install_dir/conf/jazz instead of server_install_dir/conf/ccm) you need to modify the com.ibm.stg.rtc.ext.ini file replacing "ccm" with "jazz". Also in the following steps, replace the "ccm" path with "jazz".
  2. Create a directory called "com.ibm.stg.rtc.ext.updatesite" in the path server_install_dir/conf/ccm/sites/
  3. Extract com.ibm.stg.rtc.ext_updatesite.zip into the path server_install_dir/conf/ccm/sites/com.ibm.stg.rtc.ext.updatesite/
  4. Copy the file com.ibm.stg.rtc.ext.ini into the path server_install_dir/conf/ccm/provision_profiles/
  5. In a browser, navigate to https://host:port/ccm/admin/cmd/requestReset and log in with an admin id. You should see a message the the server has been flagged to reload update-sites when it is next restarted.
  6. Restart the server
  7. Navigate to https://host:port/ccm/service/com.ibm.stg.rt.ext.ISTGVersionService/

You should see the the STG bundle version and build information. If this page doesn't load, then the STG server extensions were not installed properly and the proconditions will not work.

RTC Process Template

The attached RTC process template has to be installed in order to have access to the new Work Item Types: stg_typical_process_template.zip. Follow the typical RTC instructions on importing process templates:

  1. In an RTC Eclipse Client, import the process template from the archive file (see above)
  2. Create a new RTC Project Area based on the imported process template
  3. The preconditions to create Universal Ids have been disabled because it currently requires the repository public URI in its configuration. To re-enable the Universal Ids, follow these steps:
    1. Open the project configuration source xml
    2. Search for the text “UniversalIdAdvisor”
    3. Uncomment the xml element
    4. Change the repositoryURI attribute to the current repository
    5. Change the prefix attribute to be unique for your organization
    6. Repeat steps 2 through 5 for all instances of “UniversalIdAdvisor”

Note on permissions: The normal users are not allowed to modify many project area properties, including categories. An automated functional id is used with the STGAdmin role. To set up categories and modify your project, you can give yourself STGAdmin role. However, you should not perform normal user actions, such as creating and modifying work items, with the STGAdmin role because process and preconditions will not run. If you expect normal users to modify categories or other project area properties, you should modify the Product Owner or Scrum Master permissions to allow these actions instead of using the STGAdmin role.

Getting Started

The following are the steps of creating an STG Defect:

  • Web client:
    • Click on the Work Items dropdown
    • Click on the STG Defect

  • RTC Eclipse client:
    • Team Artifacts view: expand Project folder
    • Right click "Work Items" folder
    • Click New
    • Select Work Item

Special Considerations:

  • Required fields have red "*" after the name
  • If Owned By is left 'Unassigned' when saved, a default value based on Project configuration is used. If default is unavailable, you are required to assign a Defect owner.
  • An initial problem Description is required. The Description is editable later. But any subsequent dialog should be done by adding comments to Discussion area.
  • Other tabs may also have required fields depending on project configuration. Requiredness is not reflected in Tab label.
  • Quality tab only displayed if project uses FQI / ODC fields.
  • Use Links tab to add Attachments and/or Subscribers.
  • An Unviersal ID is given to each STG Defect to uniquely identify it across multiple repositories.

Predefined Queries

A set of predefined queries related to STG Defects and Change Records is provided:

Working with Defects

The following diagram shows the state transitions for a defect:

Notification Overview

  • Owner and submitter of Defects are automatically notified of all changes to that record.
    • Other Users who wish to receive notifications for the Defect can be added as subscribers. See next foils for details on subscribing to a Defect.
    • Owner is not explicitly listed on Defects subscription list, but they are notified (helps old owner to not receive notifications in some scenarios.)
  • Notification shows information on what was added or changed, and contains a URL link to the Defect.
  • Notifications are not sent to user making the change.
  • Notifications are sent to the email address in your RTC Profile which is not editable and was set to your email address in BluePages. 
  • Notifications are normally sent within a few minutes of change.
  • The creator, and anyone else on the subscription list of a Defect that's rejected as a duplicate, is automatically subscribed to the original Defect.
  • Defect owner is added to the Change Record's subscription list and vice versa. If Defect or CR owner changes, the new owner gets added to the other record's subscription.
  • You can use your profile in RTC to control what causes you to get notified.

Change Records

Special considerations:

  • Change Record exists as a child of an STG Defect or Task.
  • The Change Record identifies the Internal Release where an STG Defect is to be fixed, or the enhancement for a Task. The list of choices for Internal Release is specified by the Project. 
  • A Defect can have multiple Change Records if the problem needs to be fixed in multiple streams / Internal releases. (Usually there would only be one for a Task.)
  • There can only be one Change Record per Internal Release / Stream per STG Defect or Task.
  • To create a Change Record manually, use the same steps as to create 'STG Defect', except choose 'Change Record' for list of work item types.

The following diagram shows the state transitions for a defect:

Observations:

  1. A Change Record may go directly from Open, Working or 'Code Complete' to Closed if the project is so configured.
  2. Examples of using auto-generated Approvals for Change Records:
    1. Working state used if Approval is required before Change Record can be used to change code (e.g., when release nears GA.)
    2. Verify state used if Verification of fix required for each 'Change Record'.
  3. State transitions not shown for chart simplicity (following are all 1-way): 1. Open -> Code Complete; Working -> NoChange and Canceled; Code Complete -> Canceled
  4. New "Ready for Build" state and related actions not shown.

Approvals

  • Auto-generated Approvals can be configured for STG Defect and Change Records to apply business logic to your development process workflow.
  • Three types of approvals: Verification, Approval, Review.
  • Examples:
    • Defect Verification approval:
      • Auto-created for a Defect when it goes to the Verify state. (Similar to CMVC Verify subprocess.)
      • Defect submitter is automatically listed as an Approver.
      • Approval must be approved before Defect can be Closed.
      • If Approval is Rejected, Defect moves back to Working state.
      • The submitter of a Defect rejected as a duplicate is automatically added to the Approvers list for the original Defect when the original Defect goes to Verify state.
    • 'Change Record' Approval approval:
      • Can be used to require approval for code changes.
    • 'Change Record' Verification approval:
      • Can be used to verify the fix for each 'Change Record'.
  • Approvals contain a list of at least one Approver:
    • Example: work item [submitter], [owner], or a pre-defined list of UserId(s) defined in metadata by Team.
  • Approver(s) either approve or reject.
  • Approvals are added when they're ready to be approved or rejected.
  • Approvals have three possible states: Pending, Approved or Rejected.
  • If there are multiple Approvers for an Approval, all must approve, but only one needs to reject.
  • Auto-generated Approvals' title start with "*** STG AUTO-GENERATED ***" and can not be changed.
  • Notifications are sent when Approvals added and as their due date nears or is in the past.
    • Due date is configured for a project to be either:
      • # of days after Approvals created, or
      • # of days before Defect's 'Planned for' iteration's end-date (if Defect's 'Planned for' is left as 'Unassigned', Project's current iteration is used.)
  • Only Product Owners can change due date, and add or change Approver list for an Approval.
  • Additional Approvals can be added manually, but don't affect workflow.

©  Copyright IBM Corp. 1987, 2010.  All Rights Reserved.