= A proposal: New Trac Workflow = This document describes new workflow implementation for Trac. Table of contents: 1. ''Introduction'': An introduction; 1. ''Workflow Transitions'': Description of new workflow; 1. ''Automatic Ticket Assignment'': Description of ticket assignment rules; 1. ''Upgrade Notes'': Description of necessary steps for upgrading Trac projects in order to use new workflow; 1. ''Modified Files and Detailed Release Notes'': Detailed description of the changes that are included into the patch; 1. ''Future Enhancements'': Description of possible future enhancements; 1. ''Patch History'': History of all attached patches. List of attachments: * '''patch-newworkflow-r1034.diff''': Source code patch for Trac; * '''closedticket.png''': Updated icon for closed tickets in timeline; * '''resolvedticket.png''': New icon for resolved tickets in timeline; * '''reopenedticket.png''': New icon for reopened/retested tickets in timeline; * '''trac-enh-workflow.gif''': State chart diagram for new workflow. See ticket #869 also. == Introduction == ''Trac'' is a powerful and simple tracking system for ''Subversion''-based projects. It consists of logically complemented components that greatly simplify development of small-size projects. One of important features that has missed in the project is workflow system that includes support for Quality Assurance and Release Management teams. This documents includes description and implementation of new workflow system that resolves this issue for ''Trac''. It is still possible to use existing workflow with these changes. The new workflow does not remove existing workflow. Workflow version is configured in ''trac.ini'' via property ''workflow_version''. == Workflow Transitions == The workflow uses the following statuses: * '''new''': New ticket; * '''assigned''': A ticket is accepted and assigned for implementation; * '''reopened''': A ticket has not been implemented properly; * '''resolved''': A ticket has been implemented and it has to be verified by QA; * '''verified''': A ticket has been successfully tested and it has to be closed by Release Manager; * '''closed''': Closed ticket. The following picture shows the transitions using state chart diagram:[[BR]] http://projects.edgewall.com/trac/attachment/wiki/NewWorkflow/trac-enh-workflow.gif?format=raw The following table describes transitions between statuses: || From/To || '''new''' || '''assigned''' || '''reopened''' || '''resolved''' || '''verified''' || '''closed''' || || '''new''' || reassign, edit || accept || || resolve || || || || '''assigned''' || reassign || edit || || resolve || || || || '''reopened''' || || accept || reassign, edit || resolve || || || || '''resolved''' || || || reopen || reassign, edit || verify || close || || '''verified''' || || || reopen || retest || reassign, edit || close || || '''closed''' || || || reopen || retest || || edit || The following actions are used for transitions: || '''Action Name''' || '''Trac Action''' || '''Description''' || '''Team in Action''' || || '''edit''' || leave as ''status'' || Edit ticket fields without changing status and owner || Any || || '''reassign''' || reassign ticket to ''user'' || Reassign a ticket to another person. If ticket is reassigned in status ''assigned'', then status is changed to ''new'' || It depends on status || || '''accept''' || accept ticket || Accept ticket for implementation and assign it to currently logged user || Development Team || || '''resolve''' || resolve as ''resolution'' || Send a ticket to verification when it has been implemented || Development Team || || '''reopen''' || reopen ticket || Return a ticket to development because it has not been implemented properly || QA Team || || '''verify''' || verify ticket || Send a ticket to release when it has been verified || QA Team || || '''retest''' || retest ticket || Return ticket to QA because it has not been tested properly || Release Management Team || || '''close''' || close ticket || Close ticket || QA or Release Management Team || The following table lists actions for every status in details: || '''Status''' || '''Available Actions''' || '''Target Status''' || || '''new''' || leave as new[[BR]]accept ticket[[BR]]resolve as ''X''[[BR]]reassign ticket to ''X'' || new[[BR]]assigned[[BR]]resolved[[BR]]new || || '''assigned''' || leave as assigned[[BR]]resolve as ''X''[[BR]]reassign ticket to ''X'' || assigned[[BR]]resolved[[BR]]new || || '''reopened''' || leave as reopened[[BR]]resolve as ''X''[[BR]]reassign ticket to ''X'' || reopened[[BR]]resolved[[BR]]reopened || || '''resolved''' || leave as resolved[[BR]]verify ticket[[BR]]close ticket[[BR]]reopen ticket[[BR]]reassign ticket to ''X''|| resolved[[BR]]verified[[BR]]closed[[BR]]reopened[[BR]]resolved || || '''verified''' || leave as verified[[BR]]close ticket[[BR]]reopen ticket[[BR]]retest ticket[[BR]]reassign ticket to ''X'' || verified[[BR]]closed[[BR]]reopened[[BR]]resolved[[BR]]verified || || '''closed''' || leave as closed[[BR]]reopen ticket[[BR]]retest ticket || closed[[BR]]reopened[[BR]]resolved || == Automatic Ticket Assignment == A ticket is assigned automatically during status changes and when a ticket is assigned to empty user. For implementing the automatic assignment, the following fields should be configured: * '''component.owner''': The person that is responsible for developing of a component; * '''component.qaowner''': The person that is responsible for testing of a component (QA Engineer); * '''milestone.owner''': The person that is responsible for a milestone (Release Manager). The following table lists the rules that are used for auto-assignment. Note that auto-assignment is stopped when it finds non-empty owner: || '''Status''' || '''Assignment rules''' || || new || Use ''component.owner'', then ''milestone.owner'' || || assigned || Use currently logged user || || reopened || Use ''component.owner'', then ''milestone.owner'' || || resolved || Use ''component.qaowner'', then ''milestone.owner'' || || verified || Use ''milestone.owner'', then ''ticket reporter'' || || closed || N/A || == Upgrade Notes == The following steps should be performed for upgrading existing projects: 1. If the sources are not integrated into main Trac release: 1. Refresh source code tree from http://svn.edgewall.com/repos/trac/trunk; 1. Apply attached patch; 1. Add attached files '''closedticket.png''', '''resolvedticket.png''', and '''reopenedticket.png''' to directory '''htdocs'''; 1. Install Trac by running '''setup.py install''' 1. Upgrade every project by running '''trac-admin ''project-path'' upgrade'''; 1. Settings for several predefined reports are overridden during the upgrade. If standard reports have been customized for a project, then it is necessary to repeat the customization using the following steps: 1. Go to directory ''' ''project-path''/db'''; 1. Dump existing project by running '''sqlite trac.db .dump >dump.new''' 1. Dump original project by running '''sqlite trac.db.7.bak .dump >dump.old''' 1. Diff the dumps and analyze the difference in reports (ignore other changes); 1. Login into the project as an administrator and edit appropriate reports. 1. For every project where enhanced workflow is required: 1. Run '''trac-admin ''project-path'' '''and configure the project: 1. Review and modify ''components''. Specify '''owner''' and '''qaowner''' for every component; 1. Review and modify ''milestones''. Specify '''owner''' for every milestone. 1. Finally, edit''' ''project-path''/conf/trac.ini''' and change property '''workflow_version''' to '''2''' (section '''ticket'''); == Modified Files and Detailed Release Notes == Many files have been modified and below list describes the changes. The patch is also available. * Files '''wiki-default/TracIni''', '''wiki-default/TracAdmin''', '''scripts/trac-admin''', '''trac/db_default.py''', '''trac/Environment.py'''; Added '''trac/upgrades/db8.py''': * Property ''workflow_version'' added to ''trac.ini'', section ''tickets'': * For new projects and by default, it equals to '''2''' and new workflow is used; * For upgraded projects, it equals to '''1''' and current (old) workflow is used; * The version of workflow can be changed at any time. * New ticket statuses ''resolved'' and ''verified'' added: * Status ''resolved'' is used by QA for testing; * Status ''verified'' is used by Release Manager for releasing a product. * New resolution status ''moved'' added. It is used when a ticket is moved from one project to another; * New field ''qaowner'' added to ''components''. It defines QA engineer that is responsible for a component: * Command '''trac-admin component add''' modified so that ''qaowner'' can be specified. If it is omitted, then ''qaowner'' equals to ''owner''; * Command '''trac-admin component chown''' modified so that ''qaowner'' can be specified. * New field ''owner'' added to ''milestones''. It defines a person that is responsible for a milestone (e.g. Release Manager): * Command '''trac-admin milestone add''' modified so that ''owner'' can be specified; * Command '''trac-admin milestone chown''' added for changing an owner of a milestone. * Added new default reports for simplifying usage of new workflow: * For querying not closed defects: * ''Open Tickets, Mine first''; * ''Open Tickets by Version''; * ''Open Tickets by Milestone''; * ''Open Tickets by Owner''; * ''Open Tickets by Status''. * For processing resolved defects by QA: * ''Resolved Tickets, Mine first''; * ''Resolved Tickets by Milestone''; * ''Resolved Tickets by Owner''. * For processing verified and closed defects by Release Manager: * ''Verified Tickets by Milestone (Full Description)''. * Default report ''All Tickets by Milestone'' renamed to ''Active Tickets by Milestone'' because existing name does not correspond to what is produced by the report; * Default report ''My Tickets'' updated so that new statuses are queried; * Default reports enhanced in order to handle empty values properly: * '''Not Assigned''' displayed as group name for empty ''owner'' or ''milestone''; * '''Not Specified''' displayed as group name for empty ''version''; * Database version changed to '''8'''. Affected tables including reports are updated during database upgrade. Old workflow is used by default after the upgrade. * Files '''trac/Ticket.py''', '''templates/ticket.cs''': * New workflow is used when ''workflow_version'' equals to '''2''' in ''trac.ini'', section ''ticket''. See separate chapter '''Workflow Transitions''' for details; * Owner is calculated automatically when statuses are changed. The cacluation depends on currently logged user, status, component owner, component qaowner, milestone owner, and ticket reporter. See separate section '''Automatic Ticket Assignment''' for details; * Displayed ticket actions depend on current workflow version; * Files '''trac/Milestone.py''', '''trac/Roadmap.py''', '''templates/roadmap.cs''', '''templates/milestone.cs''': * Word '''resolved''' is replaced with word '''completed''' in order to eliminate conflict with status ''resolved''; * New statuses used when percentage is calculated: * ''Active Tickets'' include tickets for developers and QA, e.g. statuses ''new'', ''assigned'', ''reopened'', and ''resolved''; * ''Completed Tickets'' include tickets for Release Manager and closed tickets, e.g. statuses ''verified'' and ''closed''. * ''Milestone owner'' can be changed when milestone is edited; * ''Milestone owner'' is displayed near ''milestone date'' when it has been specified; * New statuses are taken into account when information is downloaded in ''iCalendar'' format. * Files '''htdocs/css/timeline.css''', '''htdocs/closedticket.png''', '''trac/Timeline.py''', '''templates/timeline_rss.cs''', '''templates/timeline.cs'''; Added '''htdocs/resolvedticket.png''': * The ''resolved'' and ''verified'' tickets added to timeline when new workflow is used; * ''Milestone owner'' is retrieved from database for RSS; * New icons are used for ''resolved'', ''closed'', and ''reopened''/''retested'' tickets in timeline. * File '''trac/Wikiformatter.py''': * Ticket status is displayed in popups for ticket numbers. == Future Enhancements == Proposed implementation has been tested and it is ready for using. However, the following further enhancements are visible: * Roadmap and Milestone enhancement: In progress line, display amount of defects separately by every status. For example, ''Active Tickets'' include statuses ''new'', ''assigned'', ''reopened'', and ''resolved''. Different colors can be used for these statuses on a progress bar so that user sees where is the delay in active tickets. The same is applied to ''Completed Tickets'', where different colors can be used for ''verified'' and ''closed'' tickets. * Ticket auto-assignment enhancement: Add owner for ''version'' records. It can be used when ''component'' and ''milestone'' do not have owners. This allows defining responsibilities for released versions of a product. * Ticket workflow enhancement: Add status ''testing'' for QA. It is similar to ''assigned'' but it is used for testing. This is important for the projects where testing of a ticket takes significant amount of time and it is necessary to track testing progress in details. * Ticket workflow enhancement: Add status ''unconfirmed'' for new tickets. This status is used as the initial status for a ticket is user-reporter does not belong to some "core" team. It can be configured via additional permission TICKET_CREATE_NEW. * Ticket workflow enhancement: Allow actions and fields editing depending on permissions for logged user. == Patch History == * '''patch-newworkflow-r1016.diff''': Patch that includes one more non-related change (see #892 for more details). Also, this patch has merge conflicts with current codebase. Also, this patch does not contain support for separate icon for reopened/retested tickets. * '''patch-newworkflow-r1008.diff''': Patch that includes non-related to workflow changes. They have been removed in favour of #877, #878, #879, and #880. * '''patch-newworkflow-r1003.diff''': Original patch. It the patch, Advanced Query screen does not allow to query by empty values in custom fields. ---- Final notes: * I would like to thank Trac development team for their effort and for this project. * In case if a question or a suggestion occurs, email me to ''pkou'' at ''ua.fm''. Bye!