Trac ticket workflow: Difference between revisions

From OLPC
Jump to navigation Jump to search
mNo edit summary
Line 61: Line 61:


== User Story ==
== User Story ==

=== Characters ===

:''Alice'' -- generic (possibly minimally skilled) Trac user.
:''Terry'' -- ticket herder who watches incoming tickets and improves their quality.
:''Carol'' -- coder who diagnoses, designs, codes, and reviews code.
:''Mark'' -- module maintainer (packager) aggregates code and pushes it into build streams (i.e. into [[Developer/Fedora|Fedora]] or [[Build system#Instructions for use|Joyride]]).

=== Story ===


# Alice observed curious behavior while exploring the system. She records it in Trac but does not set the <tt>next action</tt> field.
# Alice observed curious behavior while exploring the system. She records it in Trac but does not set the <tt>next action</tt> field.
# Bob decides Alice's reported behavior is erroneous but doesn't know how to reproduce it so he changes the <tt>next action</tt> to ''reproduce'' to indicate his need for instructions on how to reproduce the issue.
# Terry decides Alice's reported behavior is significant but doesn't know how to reproduce it so he changes the <tt>next action</tt> to '''reproduce''' to indicate his need for instructions on how to reproduce the issue.
#* Terry might instead have closed Alice's ticket as ''invalid'', ''worksforme'', etc or have sent it on to a later state if Alice wrote a particularly good ticket.
# Carol can reproduce Alice's behavior but doesn't understand its root cause so she changes the ticket's <tt>next action</tt> to ''diagnose''.
#* If necessary, Terry would also fill in the Milestone, Component, Keywords, and CC fields to conform to our [[Trac conventions]].
# Don diagnoses Alice's behavior and changes the <tt>next action</tt> to ''design'' to indicate that he is needs a ''design''.
# Once Alice's behavior can be reproduced, it can be '''diagnose'''[d] by Carol (probably with help from Alice).
# Eve provides a design and changes the <tt>next action</tt> to ''code''.
# Carol will eventually propose a '''design''' that she thinks will resolve the issue.
# Frank implements the design and changes the <tt>next action</tt> to ''review''.
# Geraldine reviews Frank's changes and asks for a ''testcase''.
# Carol will '''code''' to her design and will seek '''review''' of her work. She will also write a '''testcase'''.
# When all is in order, Carol or Mark will '''package''' the changes and add them to a development build (in the '''add to build''' state).
# Harry accepts merges the reviewed changes into a ''package''.
# When built in Joyride, Carol or Mark will '''test in build'''.
# Ia adds Harry's package to a development build and requests that the package be checked by setting <tt>next action</tt> to ''test in build''.
# John tests the development build Ia triggered. He records his results and may send the issue back to an earlier state (e.g. for a fresh diagnosis) or may send it forward into one of ''approve for release'' (if change control is active), ''qa signoff'', ''finalize'', or ''no action''.
#* If the test fails, then the tester may remand the issue to an earlier state and owner; otherwise, the tester should advance the ticket to the next state (see below).
# ''During change control'', changes must pass through three additional steps:
#* If the next action is ''approve for release'', then the release manager, Karl, will make sure the [[#Approval for Release|requirements for approval]] are satisfied and will push the ticket back to an earlier state (if they are unsatisfied), will slip the issue into the next release, or will approve the changes. If approved, they will go into the ''add to release'' state, then the ''test in release'' state, then either a
## Changes cannot be committed to the stable build stream without meeting [[#Requirements for Approval|basic requirements]]. Tickets in the '''approval for release''' state will be regularly examined by the [[Release team]].
#* Lily from QA retests the issue and moves the ticket to ''finalize'' because she thinks that the release notes need to be updated.
## Approved changes will be sent to the build team in the '''add to release''' state.
#* Mark updates the release notes and, at last, sets <tt>next action</tt> to ''no action'' and resolves the ticket as ''fixed''.
## Once added, the ticket will be put in the '''test in release''' state for further testing.
# ''Occasionally'', an issue require test facilities beyond those available to ordinary developers and testers or are so important that they require additional [[systematic testing]]. Such issues should pass through the '''qa signoff''' state.
# Eventually, ''user-facing issues'' will need to be documented in the [[Release Notes]]. This occurs in the '''finalize''' state.
# Ultimately, tickets which require ''no further action'' can be ''closed''.


[[Category:Trac]]
[[Category:Trac]]

Revision as of 23:38, 3 September 2008

Workflow States

Here is an approximate common path, subject to circumstances, followed by a toy user story.

A Trac ticket's position in the workflow is recorded in its Action Needed field. This field can contain the following values:

 (everyone should):
 reproduce       --  first we need to know how to reproduce your issue
 diagnose        --  then its root cause needs to be diagnosed
 design          --  at which time we can design...
 code            --  and code a fix.
 review          --  to ship the fix, we need to review it,
 testcase        --  write a test case for it,  
 
 (module maintainers should):  
 package         --  and package it up as an RPM, an activity, etc.
 add to build    --  then package needs to be added to a development build
 
 (everyone should):
 test in build   --  and the packaging needs to be tested.
   
 (during change control):
 approve for release --  get approval to add the package to a stable build stream (stable builds only)
 add to release  --  approved changes need to be committed
 test in release --  and retested at least once...
 
 (everyone should):
 qa signoff      --  some developers will want QA to review their work... (optional)
 finalize        --  before being added to the release notes
 no action       --  and closed.


Approval for Release

We enter change-control near the end of each release (e.g. 8.2.0 release schedule). When we enter change control, the ticket workflow expands to include the 'approve for release', 'add to release', and 'test in release' actions.

In order to pass the 'approve for release' action, you are expected to provide:

packages
a complete list of the packages (in source: (E)NVR form, e.g. koji: rainbow-0.7.20.fc9) which must be included to effect your change.
changelog
a nice human-readable description of your change including citations of tickets that will need to be updated as it is processed.
testcases
checkable test cases in either the |TestCase| Sugar style, the Systematic testing style, or the Tinderbox style.
(optional) risk assessment
an explanation, if convenient, of what risks are incurred by accepting your change.


General Notes

  • After testing in a build, the developer tags the bug with the results, e.g.:
 joyride-2126:-    or   joyride-2126:+
 ( '-' means bad result, try again, whereas '+' means good result )
  • The purpose of the finalize state is for the release team to provide any user-facing documentation or to conclude that no documentation is necessary.
  • The workflow can be exited early by resolving a ticket as 'worksforme', 'invalid', etc.
  • At various times, someone (e.g. the developer or the release team) may need an answer to a question. In this event, the ticket's next action should be set to 'communicate'.
  • Finally, the other 'Action Needed' states can be used to describe ignorance about what sort of action is needed. The regular Trac triage process will be responsible for pushing these tickets along.


User Story

Characters

Alice -- generic (possibly minimally skilled) Trac user.
Terry -- ticket herder who watches incoming tickets and improves their quality.
Carol -- coder who diagnoses, designs, codes, and reviews code.
Mark -- module maintainer (packager) aggregates code and pushes it into build streams (i.e. into Fedora or Joyride).

Story

  1. Alice observed curious behavior while exploring the system. She records it in Trac but does not set the next action field.
  2. Terry decides Alice's reported behavior is significant but doesn't know how to reproduce it so he changes the next action to reproduce to indicate his need for instructions on how to reproduce the issue.
    • Terry might instead have closed Alice's ticket as invalid, worksforme, etc or have sent it on to a later state if Alice wrote a particularly good ticket.
    • If necessary, Terry would also fill in the Milestone, Component, Keywords, and CC fields to conform to our Trac conventions.
  3. Once Alice's behavior can be reproduced, it can be diagnose[d] by Carol (probably with help from Alice).
  4. Carol will eventually propose a design that she thinks will resolve the issue.
  5. Carol will code to her design and will seek review of her work. She will also write a testcase.
  6. When all is in order, Carol or Mark will package the changes and add them to a development build (in the add to build state).
  7. When built in Joyride, Carol or Mark will test in build.
    • If the test fails, then the tester may remand the issue to an earlier state and owner; otherwise, the tester should advance the ticket to the next state (see below).
  8. During change control, changes must pass through three additional steps:
    1. Changes cannot be committed to the stable build stream without meeting basic requirements. Tickets in the approval for release state will be regularly examined by the Release team.
    2. Approved changes will be sent to the build team in the add to release state.
    3. Once added, the ticket will be put in the test in release state for further testing.
  9. Occasionally, an issue require test facilities beyond those available to ordinary developers and testers or are so important that they require additional systematic testing. Such issues should pass through the qa signoff state.
  10. Eventually, user-facing issues will need to be documented in the Release Notes. This occurs in the finalize state.
  11. Ultimately, tickets which require no further action can be closed.