A proposal: New Trac Workflow

This document describes new workflow implementation for Trac.

Table of contents:

1. Introduction: An introduction;
2. Workflow Transitions: Description of new workflow;
3. Automatic Ticket Assignment: Description of ticket assignment rules;
4. Upgrade Notes: Description of necessary steps for upgrading Trac projects in order to use new workflow;
5. Modified Files and Detailed Release Notes: Detailed description of the changes that are included into the patch;
6. Future Enhancements: Description of possible future enhancements.

List of attachments:

• patch-newworkflow-r1003.diff: Source code patch for Trac;
• closedticket.png: Updated icon for closed tickets in timeline;
• resolvedticket.png: New icon for resolved 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 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 picture shows the transitions using state chart diagram:

​http://projects.edgewall.com/trac/attachment/wiki/NewWorkflow/trac-enh-workflow.gif?format=raw

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 accept ticket resolve as X reassign ticket to X	new assigned resolved new
assigned	leave as assigned resolve as X reassign ticket to X	assigned resolved new
reopened	leave as reopened resolve as X reassign ticket to X	reopened resolved reopened
resolved	leave as resolved verify ticket close ticket reopen ticket reassign ticket to X	resolved verified closed reopened resolved
verified	leave as verified close ticket reopen ticket retest ticket reassign ticket to X	verified closed reopened resolved verified
closed	leave as closed reopen ticket retest ticket	closed reopened 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;
   2. Apply attached patch;
   3. Add attached files closedticket.png and resolvedticket.png to directory htdocs;
   4. Install Trac by running setup.py install
2. Upgrade every project by running trac-admin project-path upgrade;
3. 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;
   2. Dump existing project by running sqlite trac.db .dump >dump.new
   3. Dump original project by running sqlite trac.db.7.bak .dump >dump.old
   4. Diff the dumps and analyze the difference in reports (ignore other changes);
   5. Login into the project as an administrator and edit appropriate reports.
4. 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;
      2. Review and modify milestones. Specify owner for every milestone.
   2. 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;
  • Renaming and deletion of records in trac-admin lead to modification of dependent tables and properties:
    • Properties default_component, default_priority, default_severity, default_version, default_milestone in trac.ini renamed if default component/priority/severity/version/milestone renamed;
    • Properties default_component, default_priority, default_severity, default_version, default_milestone in trac.ini cleared if default component/priority/severity/version/milestone deleted;
    • Ticket fields priority, severity renamed if priority/severity renamed;
    • Ticket fields priority, severity changed to default when appropriate priority/severity deleted;
    • Ticket fields version and milestone cleared when appropriate milestone/version deleted.
  • 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;
  • Values for resolution field are not hardcoded anymore.

• 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;
  • Property default_milestone from trac.ini is updated when default milestone is renamed or deleted. When default milestone is deleted, the default_milestone is changed to new milestone;
  • 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 and closed tickets in timeline.

• Files trac/Query.py, templates/query.cs:
  • New statuses are displayed when new workflow is used;
  • Lists sorted properly for Status, Resolution, Priority, and Severity;
  • Tickets can be queried by empty values:
    • For lists Component, Milestone, and Version, new choice (empty) is available for selection;
    • For edit fields like Assigned To, Keywords, etc, value (empty) should be entered;
    • Note: This feature has not been implemented for custom fields.
  • Field Resolution is enabled for selection when user does not select statuses new, assigned, or reopened for a query.

• File trac/Wikiformatter.py:
  • Ticket status is displayed in popups for ticket numbers (e.g. #number).

• File trac/Notify.py:
  • Email notification for tickets is stopped when it is turned off.

• Files trac/Report.py, templates/report.cs:
  • Report title has corrected when a report is edited or new report is created;
  • Report title has corrected when a report is deleted.

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.
• Query enhancement: Allow filtering by empty values for custom fields.
• 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.

---

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!