Issue (Agile)

Issues are used to track events that may block progress or shipping a user story. Bugs, on the other hand, are used to track code defects.

In this topic, you can learn how to fill in the details of an issue work item. For information about how to create this type of work item, see Add, Find, View, Update Status, and Modify a Work Item.

In this topic	Related topics
Defining an Issue Linking an Issue to a User Story, Task, or Other Work Item Adding Details, Attachments, or Hyperlinks to an Issue Closing Issues	Workbooks Issues Workbook Field Reference Assignments and Workflow Field Reference Areas and Iterations Field Reference Planning, Ranking, and Priorities Field Reference Titles, IDs, Descriptions, and History Field Reference Link Controls, Restrictions, and Field Reference Attachment Controls and Field Reference

Required Permissions

To view an issue, you must be a member of the Readers group or your View work items in this node must be set to Allow. To modify an issue, you must be a member of the Contributors group or your Edit work items in this node permissions must be set to Allow. For more information, see Managing Permissions.

Defining an Issue

The work item form for an issue stores data in the fields and tabs that are shown in the following illustration:

To define a single issue

1. In Title (Required), type a short description of the event or cause that may delay shipping.

2. Specify the following information:

   • In the Assigned To list, choose the name of the team member who is responsible for addressing the issue.

     This list is auto-populated with the names of all accounts that have been added to the team project.

   • For Area and Iteration, choose the appropriate area and iteration, or leave these fields blank to be assigned later during a planning meeting.

     Note

     Your project administrator defined the Area and Iteration tree hierarchies so that team members can track progress by those designations. For more information, see Create and Modify Areas and Iterations.

   • Leave the Stack Rank value as is.

     For more information about how to rank and prioritize issues, see Issues Workbook.

   • In the Priority list, choose the level of importance of the issue on a scale of 1 to 4, 1 being most important.

     By default, this value is 2.

   • Select the Due Date by which the issue needs to be resolved.

3. On the DESCRIPTION tab, provide as much detail as you want to describe the issue.

4. On the HISTORY tab, provide as much as detail as you want.

   You can format the text that you type in this box.

   Every time that a team member updates the work item, its history shows the date of the change, the name of the team member who made the change, and the fields that changed.

5. Link the issue to other work items, such as a user story or task.

   For more information, see the next section in this topic.

6. Choose Save Work Item.

Linking an Issue to a User Story, Task, or Other Work Item

On the Links tab, you can link an issue to another work item.

To link an issue to a user story, a task, or another work item

1. On the Links tab, choose Link to.

   The Add Link to Issue dialog box opens.

2. In the Link Type list, choose Related.

3. Perform one of the following actions:

   • In Work item IDs, type the IDs of the work items that you want to find. Separate IDs by commas or spaces.

   • Choose Browse to specify work items from a list.

     The Choose linked work items dialog box appears.

     

     In the Saved query list, choose a query that contains the work items that you want to add. For example, you can choose Open User Stories or Open Tasks.

     Choose Find, and then select the check box next to each work item that you want to link to the issue.

     Choose OK.

   • (Optional) Type a description for the items that you are linking to.

4. Choose OK.

   For more information, see Find Work Items to Link or Import.

5. Choose Save Work Item.

   Note

   Both the issue and the items to which you linked are updated. A Related link to the issue is defined for each work item that you added.

Adding Details, Attachments, or Hyperlinks to an Issue

You can add information to an issue as more information becomes available. You add details to an issue in the following ways:

• Type information in the Description or History field.

• Attach a file.

  For example, you can attach an e-mail thread, a document, an image, a log file, or another type of file.

• Add a hyperlink to a Web site or to a file that is stored on a server or Web site.

To add details to an issue

1. Choose the Details tab.

2. Type information in the Description field.

3. (Optional) Type information in the History field.

   You can format information to provide emphasis or capture a bulleted list. For more information, see Titles, IDs, Descriptions, and History Field Reference.

4. Choose Save Work Item.

To add an attachment to an issue

1. On the Attachments tab, perform one of the following actions:

   • Drag a file into the attachment area.

   • Choose or press CTRL-V to paste a file that you have copied.

   • Choose Add, choose Browse, and, in the Attachment dialog box, type or browse to the name of the file that you want to attach.

     (Optional) In the Comment box, type additional information about the attachment. To close the Attachment dialog box, choose OK.

2. Choose Save Work Item.

To add a hyperlink to an issue

1. On the Links tab, choose Link to.

   

2. In the Link Type list, choose Hyperlink.

3. In the Address box, perform one of the following actions:

   • If the target is a Web site, type the URL, or copy it from your Internet browser and paste it into the Address box.

   • If the target is a server location, type its UNC address.

4. (Optional) In the Comment box, type additional information about the hyperlink.

5. Choose OK.

6. Choose Save Work Item.

Closing an Issue

After an issue has been resolved and is no longer blocking progress, you change the state from active to closed. For more information about data fields that track states of work items, see Assignments and Workflow Field Reference.

To close an issue

1. Open the issue.

2. In the State list, choose Closed.

3. Choose Save Work Item.

Typical workflow progression: A team member creates an issue in the Active state with a default reason of New. A team member changes the state from Active to Closed when the issue is resolved or no longer blocking progress. Additional workflow transitions states: A team member determines that the issue was closed in error and reactivates the issue by changing the state from Closed to Active.

Issue State Diagram

Active (New)

All work items are created in the Active state. Each issue remains in the active state as it is being implemented. The team member who is assigned to the issue tracks its progress and that of any user stories, tasks, or other work items that it affects.

From Active to Closed

When you close an issue, the Assigned To field is automatically populated with the name of the team member who created the issue, and the Reason field is set to Issue Resolved.

The following data fields are automatically captured during the transition from active to closed:

• Closed By: Name of the team member who closed the work item.

• Closed Date: Date and time when the work item was closed, as recorded by the server clock.

• State Change Date: Date and time when the state for the work item was changed.

Closed

Any team member can reactivate a closed issue if it was closed in error.

From Closed to Active

When you reactivate an issue, the Assigned To field is automatically populated with the name of the team member who closed the issue. The Reason field is set to Reactivated.

The following data is automatically captured during the transition from closed to active:

• Activated By: Name of the team member who reactivated the work item.

• Activated Date: Date and time when the work item was reactivated, as recorded by the server clock.

See Also

Concepts

Issues Workbook

User Story (Agile)

Other Resources

Agile Process Template for Visual Studio ALM

Work Items and Workflow (Agile)