Issue Manager provides a default workflow for each type of issue—bug, doc-issue, and enhancement. These are shown in “Understanding the Default Workflows”. If these workflows don’t meet your organization’s needs, you can change them. You can customize:
• The number and name of the states that an issue passes through.
• Which actions are valid on a particular state. These actions appear on the Workflows window.
• Which
states result from each action on the current state; that is: Current
State ---- Action 1 ---> New State 1
Current State ---- Action 2 ---> New State 2
...and so on.
• Which groups have permission to perform each action.
• The appearance of the action dialogs that are displayed when users take action on issues.
Recommended approach
The easiest and most reliable approach is to make simple modifications to the default workflows (e.g., edit a state name). It is strongly recommended that you modify the default workflows rather than create a new workflow from scratch, especially if you have little or no experience with the concepts presented in this chapter.
Familiarize yourself with the concepts of state diagrams and actions, also called state transitions.
General steps in developing a workflow
In this section you will prepare a paper-and-pencil or whiteboard model of your organization’s process for resolving issues. We recommend that you meet with the appropriate managers and other individuals to formalize the optimal process for handling issues in your organization.
The general steps to developing a workflow are as follows. Repeat these steps for each issue type.
1 Make a state diagram:
- Draw each state that an issue of this type must pass through until it reaches a terminal state.
- Draw each action that can be performed on this type of issue until the terminal state is reached. Include “negative” actions that cause an issue to return to a previous state in the workflow.
2 Name the actions with verbs.
3 Optimize the workflow.
4 Add state owners and permissions.
5 Decide on the initial issue states for groups and users.
6 Prepare for data entry (optional).
Draw a state diagram on a whiteboard or paper. Make sure to draw each state in a box with plenty of space between each state.
Draw each legal action between states as a line with a single arrow head. Each direction is a distinct action.
Example
The following example is a small sample of the states you might have in your own workflow. When a new bug is entered, someone in your organization dispatches the bug to the appropriate QA engineer for review. If the QA engineer agrees that the reported behavior is a new bug, then it is sent to Development to be fixed. Development can take a number of possible actions on the bug.
• The behavior described in the bug report is designed behavior, so the issue is not a bug.
• The bug should be deferred until the next release.
• The bug cannot be reproduced.
• The bug is fixed.
Of course, these are only the developer’s claims and have yet been verified. Your workflow model might reflect these claims with the following states: Fixed?, Deferred?, Not Repro?, and Not-a-Bug? The question marks imply that these claims have not yet been verified by a QA engineer.
Verification by a QA engineer is the last step in the workflow. If the claims are verified, then the bug moves to one of four terminal states, which have the same name as the prior state, but without the question mark.
It’s recommended that you assign a verb to each action.
Think about times when a bug might return to an earlier state in the workflow. Model these negative actions. For example, a QA engineer might reject a developer’s claims, which returns an issue to Development.
You may also uncover missing positive actions while considering each way that an issue can travel. For example, you realize that QA engineers also reject some issue reports, in effect closing the issues. In the example diagram below, the Reject Bug action by a QA engineer leads to the Not-a-Bug state. Ensure that all actions eventually lead to a terminal state.
Revised example
All changes to the sample workflow diagram are shown in boldface.
As you can see, the preceding diagram is too complicated to be useful. To simplify the workflow you can eliminate the Dispatch action because Issue Manager’s routing rules take care of distributing bugs to the correct inboxes. In the preceding diagram you can delete the New-Bug state and the Dispatch action and start the bug in a state where a QA engineer can review it. You might call this the Unreviewed state.
Another flaw in the workflow is the virtually repetitive states. Using Issue Manager’s methodology, you can eliminate redundant states by assigning reason codes to actions. For each action that requires a reason code, devise a brief, descriptive keyword. For a full explanation of reason codes, please read “Reason codes”. To identify redundancies, look for repeated patterns in the workflow. For example, in the previous diagram, the last row of states (Not-a-Bug, Deferred, Not-Repro, and Fixed) can be collapsed into the single state of Closed with a different reason code for each action (e.g., Closed/Not-a-Bug, Closed/Fixed).
The next-to-last row can also be collapsed into a single state that recognizes QA’s role in verifying Development’s claims. You might call this state QA-Ready. You can use reason codes here to explain why a bug has changed states (e.g., a bug arrives in the QA-Ready state with a reason code of Fixed or Deferred). The four Rejected actions taken by QA can be collapsed into a single Rejected action. Similarly, the four Verified actions taken by QA can be collapsed into a single Verified action.
Revised example
Here’s a cleaner optimized workflow diagram, with the dispatching action and redundancies eliminated:
Add State Owners and Permissions
In Issue Manager issues are routed according to issue state and state owner. A state owner is a role in your organization that is responsible for an issue in a given state. For example, in the default workflow, QA has responsibility for issues in the Unreviewed state. For more information on state owners, see “State owner”. Now you must assign an owner to each state in your final diagram.
Finally, decide which groups should have permission to take each action. In the default workflow, for example, only users in Development are allowed to fix issues (i.e, take the Fixed action).
Prepare a Data Entry Sheet
Optionally, prepare a sheet to facilitate data entry into Issue Manager. The workflow information is entered by state, so the first column should be current state and owner. Then add the following column headings:
• Actions allowed on the current state
• New state resulting from each action
• Reason code (if applicable)
• Permissions - The group(s) that are allowed to take each action
Your data entry sheet should resemble the following:
|
State/Owner |
Actions |
New State |
Permissions |
|
|
|
|
|
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
|
|
|
|
|
|
| |
|
|
|
| |
|
|
|
| |
|
|
|
|