team-1193.doc
Last saved: March 25, 2008

UCM to Jazz Work Item Bridge

Shirley Hui

Description of relationship between Jazz Work Item and ClearCase UCM

1                        Overview

We would like to provide the capability for ClearCase users to associate UCM activitieswith Jazz work items. Users will be able to use Jazz planning capabilities for projects dependent on ClearCase.

2                        Phase 1 Goals

Define a loose integration between UCM activity and Jazz work item

The goals for this phase are

·         to establish the communication path between the two products

·         to have the ability to access and report relevant data from the other repository

·         to have a base for experimenting with Jazz functionality (e.g. process rules)

·         to gain experience and knowledge to be used for the next phase

The goal is to connect the UCM activity and the Jazz work item, allowing each product to work to its strength, adding the ability to obtain data about the related object from the other product.

3                        Phase 1 Link Jazz work items and UCM activities

Implement the ability to link a Jazz work item to any number of UCM activities.  Implement the ability to link a UCM activity to any number of Jazz work items.

3.1                  UCM Project

·         Jazz-enable a UCM project with Jazz repository URI

·         Jazz-disable a UCM project

·         Display the relationship – one way linkage for phase 1?

3.2                  UCM Activity

·         “Associate work item” action on UCM activity

o        Create new work item (using work item editor)

o        Select existing work item (using work item picker dialog)

·         “Dissociate work item” action on UCM activity

·         Show associated work items anywhere an activity is displayed

·         “Open work item” action available on associated work items

3.3                  Work Item

·         Show associated UCM activities

·         Allow display of UCM activity details (properties? Change set?) from work item

3.4                  Explicit Omissions from Phase 1

We are deliberately not discussing process and builds in this phase.

4                        Assumptions

This implementation will support the basic Jazz work item and the Zydeco (enhanced) work item.

The bridge will be functional from both products, Jazz and ClearCase.  Each product will be aware that there is a relationship between them and additional functionality is available based on the ability to retrieve data from the other product.

There is no relationship between this bridge implementation and the existing UCM/CQ integration.

This proposal does not cover a bridge between base CC and Jazz work item.  This is will be considered separately.

A UCM project may be enabled with the bridge to Jazz work items or the existing CQ (SQUID) integration.  You may not enable both.

We'll assume that the user is appropriately connected (or logged into) each product.  The user identity is managed in each separately and the user has appropriate permissions to perform the request operations.

5                        Basic Object Mapping

A UCM project and its integration stream is mapped to a Jazz Repository

You may associate a UCM activity with any Work Item

You may associate more than one UCM activity with a Work Item.

You may associate a UCM activity with more than one Work Item.

6                        Phase 2 and future

Future phases TBD.

Consider relationship of Project Areas and Team Areas when enabling a UCM project. Display relationship from Jazz Project Area or Team Area.

Associate activities from Jazz Work item context.

Consider restrictions when associating Work Items and Activities.  Might be related to Team Areas.

Consider restrictions when removing associations.

7                        Release and Support Issues

The prototype will probably support 7.0.x. Implementation issues to be determined.

It's likely the initial deployment of this bridge will be in customer installations with 7.0.x.  7.1 will not be widely deployed yet.

Do we have issues migrating an existing CQ-enabled project to a Jazz work item enabled project?

8                        Basic Usage Scenario

In the bigger picture, how and what we implement should be useful to our customers.  What does the relationship between UCM activities and Jazz work items provide?

This section describes how the developer works with UCM activities and Jazz work items

8.1                  Original Scenario

I took this scenario from https://jazz.net/learn/LearnItem.jsp?href=content/docs/platform-overview/index.html

This is the original text:

"Let's look at a typical scenario in software development. Zoë, a software developer, refreshes the "My Bugs" page in her web browser and sees a new bug report has been assigned to her by Rick, her team lead. She opens her Eclipse IDE and finds the errant code in the workspace. She fixes it and adds a regression test to the test suite. She runs the test suite to ensure that everything is working as expected. She updates the build notes to record that the bug is fixed in the code stream. Zoë then checks in all her changes to the source code repository, using the bug report number and title as the check-in comment. Then she annotates the bug report with the scheduled build in which the fix will appear and marks the bug report as "Resolved/Fixed". Updating the bug report automatically causes e-mail to be sent to interested parties, including Mike, the team member who reported the bug. Once a build becomes available, Rick downloads it, verifies the problem is fixed, and marks the bug report as "Resolved/Verified"."

8.2                  Annotated scenario

I modified the scenario slightly, here's an annotated version.  Annotations added in this font and color

Let's look at a typical scenario in software development.  A defect is submitted, Rick, the team lead, assigns the bug to Zoe.  Zoë, a software developer, working in Eclipse, refreshes the "My Bugs" view and sees a new bug report has been assigned to her by Rick, her team lead. She switches to CCRC (in Eclipse) and finds the errant code in the workspace. She fixes it and adds a regression test to the test suite.   She runs the test suite to ensure that everything is working as expected. She updates the build notes to record that the bug is fixed in the code stream.   Omit updating build notes step. This is unnecessary – the information can be inferred from the fact that the work item for which the bug is resolved. Zoë then checks in all her changes to the source code repository, using the bug report number and title as the check-in comment.  She is not required to specify any of this - this information is captured by the association with the workitem.  Then she annotates the bug report with the scheduled build in which the fix will appear and marks the bug report as "Resolved/Fixed". Updating the bug report automatically causes e-mail to be sent to interested parties, including Mike, the team member who reported the bug. Once a build becomes available, Rick downloads it, verifies the problem is fixed, and marks the bug report as "Resolved/Verified".

8.3                  Bridged Scenario

Now, let's take this scenario apart, from the developer perspective, describing the developer actions from each product, Jazz and UCM from CCRC.   

-          Defect is submitted, Rick the team lead assigns the bug to Zoe.  The defect is in a team area that is associated with a UCM project.

-          Zoë, a software developer, working in Eclipse, refreshes the "My Bugs" view and sees a new bug report has been assigned to her by Rick, her team lead.

-          She applies the "start working" action to the defect. Display the UCM project name in a custom attribute. (We know that this Team Area is associated with the UCM project, but we want the information readily available to the developer.)

-          She switches to CCRC (in Eclipse). She has a stream and view to work in this UCM project.

-          She creates a UCM activity, or she performs a checkout, which gives her the option to create an activity.  During activity creation, she can bring up the work item picker. Associate the activity with any currently started work items in her team area.  She has the option to exclude some or all of the work items. Also, it is not required to associate the activity to a work item.

-          and finds the errant code in the workspace. She fixes it and

-          adds a regression test to the test suite.   She can add this change to the same activity or different activity.

-          She runs the test suite to ensure that everything is working as expected.

-          Zoë then checks in all her changes to the source code repository.

-          Zoe has two possible next steps.  She might deliver the fix or switch back to the Jazz view to mark the bug report as "Resolved/Fixed".  Much of this section raises questions about process – the actions require or imply some process. It's not clear what makes sense yet.  Don't get attached to anything here.

§         If her next step is to deliver the fix – her parent stream (default target) might be an intermediate feature stream or to the integration stream. 

·         She has the option to associate each activity being delivered with a Work Item.  From UCM, the association is optional.

·         Or, should it be required to associate with a Work Item at this point? If required, don't allow the operation to proceed until condition is satisfied.  How is process involved at this point?  We could add process to UCM, but we should avoid adding more policies to the UCM side; our usability issues are bad enough, it's not desirable to add more).  It would be nice if we could query the Team Area's process component for the 'require work-item to activity association' rule, but apparently there is no effective way to do this currently

·         Should/could we query to mark associated work items as "Resolved/Fixed" ?

§         Or, she is back in the Jazz interface. She marks the bug report as "Resolved/Fixed".

·         Same issues as UCM activity above. If there is no association, she has the option to associate it with a UCM activity

·         Warn the user if  the work item is not associated with an activity.  This could be annoying; not all work items need to be associated, do we need to have a work item type?

·         We could use Jazz process to require associating the bug report to an activity.

·         If the activity is not delivered < UCM question: is this activity delivered? This query is not answered easily by UCM, need to think about this>, we could query to see if she wants to do a "deliver" of the associated UCM activity to its parent stream.

-          Updating the bug report automatically causes e-mail to be sent to interested parties, including Mike, the team member who reported the bug.   

-          Once a build becomes available, Rick downloads it, verifies the problem is fixed, and marks the bug report as "Resolved/Verified". <TBD: Relationship between Jazz build and ClearCase and associate baseline with the build request>

8.4                  Additional Pieces of the Scenario

What happens after an activity is delivered? UCM activities have no state and you can continue to add versions to the change set after it is delivered.  What does it mean to add new versions to an activity associated with a work item that has been completed? Perhaps this is not allowed, you can only associate an activity with a work item in an unresolved state? You cannot setact an activity associated with a resolved work item?  (Current UCM/CQ integration has something implemented for this reason.)

Deliver or Rebase integration activities may need special treatment

-          you are not required to associate Deliver or Rebase integration activities with Work items

-          if the integration activity contains conflict resolution, the user may want to have an explicit Work item to track the change

9                        Impact of the Bridge

What will we be able to do when SCM data and planning objects are associated?  This section is speculative and incomplete.  We need more experience with the bridge and customer usage in future phases to expand and discuss this section.

9.1                  Status of the Iteration in relation to the UCM Project

Changes are either delivered directly to the integration stream, or make it upstream via deliver from intermediate task streams, following UCM best practices.   Baselines are created on the integration stream.

Work items have status.   Some or all work items are completed. 

We want to know how well the iteration is progressing in relation with the code base.

We have the ability to reconcile the set of work items in the iteration with the activities included in a baseline in the project.

Have all activities related to the work items been delivered and included in a baseline? 

The team area is associated with the UCM project.  The UCM project has an integration stream and a latest baseline, perhaps the recommended baseline.  Determine the set of activities included in this baseline.  Derive from the activities the list of work items associated with them.  Derive the list of activities that are not associated with a work item – all leaf activities should be (perhaps, by policy, required to be) associated with a work item. Most deliver and rebase integration activities do not need to be associated, although they can be.