Documentation

Introduction

Agile-Trac differs from a normal Trac install in a number of ways. Most notably it differs in how it is used. The documentation here serves mainly to clarify basic usage of Agile-Trac. It will grow over time.

To fully appreciate the facilities offered by Agile-Trac and how to make best use of them you can refer to:

The first two presentations are not specific to agile-trac but they do offer some important background that should help put the features of agile-trac into context. It is recommended that you read them.

The third presentation is specific to agile-trac and serves as a reasonably complete summary of agile-trac capabilities.

Installing Agile-Trac

Please refer to the Installation instructions for the Agile-Trac plugin.

Migrating an Sqlite Agile-Trac install to a Postgresql install

Please refer to the Migrating from Sqlite to Postgresql Guide.

Configuration Options

You may configure your Agile-Trac install by adding options to the conf/trac.ini file. All available options are listed on the Configuration Options page. The options are also summarised here for convenience.

Changes to Tickets and Workflow

There are two key changes in how tickets should be used with Agile-Trac.

1. If the work associated with a ticket is to be measured then the ticket must be relatively sized

Work (represented by tickets) will have one or more completion stages. This is configurable, however the default should suit most installations. In the default configuration the completion stages are:

  • test complete
  • documentation complete
  • acceptance complete

A relative size can be associated with each of these stages. The relative sizes that are available by default are:

undefined
0
1
3
5
8
13
20
40
100

It is possible to add more if that is required from the Admin section in Trac.

2. You progress tickets until they are DONE

For each relatively sized completion stage that is neither undefined or 0 you may progress the stage to completed by specifying a completion date. If the ticket is fully sized (that is, no relative size is undefined) and you progress all completion stages to complete, the ticket will automatically be changed to a status of closed with a resolution of DONE.

This is important. To complete a relatively sized ticket you must progress it by specifying when you complete each completion stage. Only by doing this can you change the status to closed and the resolution to DONE.

It is still possible to 'resolve' a ticket but by doing so all relative sizes for each completion stage will be set to 0. This still makes sense in a number of scenarios, for example it is sensible to resolve a ticket with the following resolutions.

Resolution Meaning
worksforme The ticket appears to work, there is nothing to do, hence the relative size should be 0
duplicate The ticket is a duplicate, the relative size will be tracked in the original ticket
split The ticket has been split into two or more new tickets. These new tickets will effectively block this one and the effort needed captured by the sum of the efforts in the new tickets. The split ticket will therefore have its relative size set to 0
wontfix This ticket will not be fixed so its relative size is set to 0. If in the future you do want to address the ticket you can reopen it and resize it.
fixed It is preferable to remove this resolution or rename it to available. This resolution should be treated as meaning that the ticket is available but it was completed some time in the past and so the effort associated with it was not tracked. Renaming fixed to available makes the distinction clear. This should also make it less likely for someone to accidentally resolve a ticket as fixed when really they wanted to progress it until it is DONE.

Workflow action and status summary

The following graphviz diagram summarises the actions available for a given status and the potential change in status that will result from taking that action. As you can see the workflow is very much simplified in so far as the number of statuses that are possible. The statuses of new, assigned, accepted and reopened are largely redundant and can be considered as a single status of unsized. The reason for retaining them is simply because it minimised the number of changes required to the basic workflow as there is sometimes value in associating a ticket with an individual. However in Agile-Trac the emphasis is on assigning a ticket to an iteration for the team to work on rather than to an individual.

It is worth noting the two closed statuses.

source:/BRANCH/TRUNK/artifacts/documents/agile-trac-workflow.png

Using the severity and priority fields in Agile-Trac

It is useful to use the ticket field severity in Agile-Trac as severity provides an indication how the reporter is impacted by the problem they encounter. This is useful information as it allows the business to understand better the importance they should attach to the issue. If the impact is considered important enough then the issue can be associated with a high priority milestone and planned for inclusion in an upcoming iteration.

The ticket field priority, on the other hand, is not so useful as you will not make use of this value directly. In Agile-Trac the priority of a story (or other issue) is reflected by the milestone it is assigned to and whether or not it will be tackled on the current or subsequent iterations. One of the key features of Agile-Trac is that milestones are ordered by priority. Issues in higher priority milestones are of higher priority. Also if something is of highest priority it will be added to the next iteration. If not then it can be added to a future iteration. Only when an issue is assigned to an iteration is it actually prioritised beyond the priority of the milestone with which it is associated.

In summary then the priority field has no value in Agile-Trac and should not be used. Conversely the severity field is a useful indicator of impact on the customer which assists in prioritisation.

How to handle raising bugs against a user story

The assumption here is that we have a user story that has been progressed to a closed status with a resolution of DONE. Some point after that the DONE resolution is called into question. One of two scenarios will exist;

  1. either the user story has not delivered the promised functionality,
  2. or additional information has come to light which means the user story is required to deliver more than originally anticipated.

In the first case the correct procedure would be to reopen the user story. It can then be prioritised into a subsequent iteration to be progressed once more to a closed:DONE state. If you have more than one completion stage you can reopen only those stages that need work. For example, assuming the default completion stages or tested, doc'ed and accepted, then a documentation change would require both the doc_complete_stage and the acceptance_complete_stage to be reopened. The status of the issue will change to sized. Reopening a previously closed issue will result in the roadmap dates being impacted as you would expect.

In the second scenario, additional information has been discovered, the correct procedure would be to create a new user story focusing on the new functionality, size the story and then prioritise into a milestone and iteration as appropriate.

Using Iterations

Agile-Trac adds a new Iterations tab. From here it is possible to add new iterations. Essentially an iteration is a period of time-boxed development, so each iteration must have a start and end date. The only requirement on start and end dates is that the end date must be later than the start date (it may also be the same as the dates are inclusive). Also, you must always specify both dates. If either of these conditions is not met you will be issued with a warning.

Iteration Overview

An Iteration has the following fields:

FieldCommentRequired
idEvery iteration has a unique idYes - this is what uniquely identifies and iteration
summaryYou may specify an optional summary that names the iteration. This makes it easier to refer to the iteration and can be used to provide an indication of the iteration goals.Not required, but it is recommended that you do provide one
start_dateThis is the inclusive date of when the iteration beginsThis is required. An iteration is defined by its start and end dates
end_dateThis is the inclusive date of when the iteration finishesThis is required. An iteration is defined by its start and end dates
descriptionYou may also specify a multi-line wiki-formatted description of the iteration to allow additional information about the iteration to be specifiedThis is an optional field and there is no requirement to provide any content for it
ticketsTo indicate that a ticket (work) will be associated with an iteration you must add its ticket id to the space-separated list of tickets in the tickets field. Internally this mapping of iteration to ticket is stored in the iteration_ticket table. This allows a mapping to be maintained between work presented in the Roadmap and work present in each iteration.If an iteration is to have any real value then you would expect that there is at least one ticket id present in the tickets field. The main purpose of the Iteration Planning Phase of an iteration is to identify which stories (tickets) will be added to the iteration.

Iteration Use

You can add existing tickets to an iteration to signify that you will spend time on the iteration working on those tickets. If a ticket is progressed such that it becomes DONE then the points for that ticket are counted against the iteration. You can see these from the Iteration Summary Table that appears at the top of the Iterations page.

The Roadmap uses this information to associate work done in a specified time period, where the specified time period is the iteration duration. It is worth noting that the ticket summary shown for each iteration captures the state of each issue at the end of that iteration, not the state of the issue now. This provides a historical view of ticket status and allows reviewing of previously completed iterations.

Using the Roadmap

The roadmap page in Agile-Trac differs in four significant ways from the usual roadmap page in Trac.

  • First there is a summary of all milestones presented in a table at the top of the roadmap page
  • Second each milestone now has associated with it an Expected Completion Date Range, with the earliest and latest expected dates shown.
  • Third each milestone has a relative priority associated with it so that milestones can be re-ordered or new milestones can be created and inserted between existing ones.
  • Each milestone has a relatively sized progress bar. This means that the work required for all the stories in a given milestone is visually represented by the relative size of the progress bar. This provides a fast visual of the comparative effort needed for each milestone in the roadmap.

Milestone Priority and Relative Weight

All milestones have a relative priority associated with them. This relative priority is determined when a milestone is inserted into the Roadmap. When adding a milestone is added it can either be:

  • Added with the same priority as another milestone
  • Be inserted into the Roadmap immediately before another milestone
  • Be inserted into the Roadmap immediately after another milestone

If a milestone is added to the roadmap with the same priority as one or more milestones those milestones are considered to be worked on in parallel. This means that Points Per Iteration is spread across each of the milestones according to the relative weighting of the milestone. The spread value is then used to determine the expected completion dates for the milestones.

For example, if the Points Per Iteration was 24 points in 20 days and you had three milestones (M1, M2 and M3) with the same priority and each with the same relative weight, then the effective Points Per Iteration for each milestone would be 8 points in 20 days.

If however we wanted to approximate the effect of having a team of 8 developers and we knew that 4 would focus on one milestone (M1) with the remaining 4 split across the remaining two milestones (M2 and M3) then we could assign a relative weight of 2 to the first milestone and leave remaining milestones at 1. We could also assign a relative weight to the first milestone of 4 and set the remaining two to 2. Either would work as we are only interested in the relative weight. In this example then we would find that the effective Points Per Iteration for M1 would be 12 with M2 and M3 both having 6.

The purpose of this feature is to allow for the fact that sometimes things need to be grouped into same priority milestones to provide a more accurate representation to stakeholders of how work is going to proceed while at the same time providing realistic expected completion dates.

How Expected Completion Dates are Calculated

Currently the method of calculating the completion dates is fairly fixed and follows roughly the formula found in the  completion_date_range.ods spreadsheet. The average points completed over the last five iterations is used as the average points completed.