YetAnotherXpTrackerPlugin

Summary

This is a plugin for light-weight project tracking, in particular suited for XP projects. The original code was written by TWiki:Main.RichardBennett, It was converted into this plugin by TWiki:Main.MartinWatt and enhanced. This plugin was further extended by TWiki:Main.ThomasWeigert. It is now maintained as a branch of the original TWiki:Plugins/XpTrackerPlugin. The focus of this branch was to support additional customizability of what is being tracked, as well as a low-overhead time tracking mechanism.

This is a branch of TWiki:Plugins/XpTrackerPlugin supporting additional needs of our organization. Please consult the description of the original plugin to decide whether you will need these additional features.

Description

Layout

Projects are tracked in a hierarchy of information:

• Web - the TWiki web for project tracking. One web can be used to track multiple products.
• Project - A group of activities. Usually this will be major releases of a product. Each project has a page, which contains a generated summary of the project progress.
• Team - A team is a group of developers that work on one or more groups of activities. Each team has a page which contains a generated summary of the team's progress.
• Iteration - Work is divided into a series of short iterations. Each iteration has a page, the contents of which are also generated.
• Story - An iteration comprises a number of stories. Stories are pieces of related functionality that are owned by a lead developer but can be worked on by more than one developer. The story page contains information on the acceptance criteria, and also a list of tasks.
• Tasks - these are the atomic units of work. A story is usually broken up into a number of tasks. Tasks may be shared among more than one developer. Tasks details are entered on the story page.

Information is entered for Stories and their associated tasks, and for iteration dates. Information for all other levels in the hierarchy is generated.

Organizations typically decide on the hierarchy of their work items. While the terminology used above is that each project is worked on by teams which handle a set of iterations, others may prefer a structure where a team works on a set of projects consisting of iterations, or others. The hierarchy is configurable via the TEAMLABEL and PROJECTLABEL variables. In this plugin, teams and projects are just organizational categories; their name can be configured by the above variables. Note, though, that the tags provided by this plugin follow the above order, so when configuring topics care has to be taken that no confusion results if an organization uses different terminology.

Example of hierarchy:

Usage

Creation of pages is recursive, each page has an html form that uses a template to create child pages:

• Projects/Teams. You can create a new team page using the html form on the home page for the tracking web. At each level of the hierarchy, additional lower level entities can be created. You can add additional content to these pages if desired, but do not delete the fields indicated below. This is used to provide high level overviews of schedule progress.
• Iterations Create new iterations from the project pages.
• Stories Create new stories from the iteration page. The story name can be any unique name, as long as it ends with the string "Story". Fill in the two tables for the story summary and task list respectively.

The content of these topics are determined by templates, having the name of the entity postfixed with Template; there is usually a form attached, which is defined in the corresponding Form. You should configure these to your need, in particular, the forms and templates defining stories. Please take care to not delete the fields indicating to which entity in the hierarchy a topic belongs (e.g., in the StoryForm, the field Iteration tells us which iteration this story belongs to). Do not delete the state field for stories. When creating a new instance of an entity, there may be a choice of templates, which is determined by the corresponding TemplateOptions topic.

YetAnotherXpTrackerPlugin sample output

The iteration status page displays the stories and tasks currently allocated to that particular interation.

Stories are displayed in the order in which they are to be developed. Stories are completed when they are marked to be in the state configured to be the STORYACCEPTEDINDICATION.

Tasks within a story are displayed in the order in which they are to be developed. Tasks are considered complete once their estimate until completion is 0 days.

Below are examples of the generated tables produced by parsing the story pages:

Show all iterations in a project - XPSHOWPROJECTITERATIONS

Show summary of iterations in a project - XPSHOWITERATIONTERSE

Show details of iterations in a project - XPSHOWITERATION

Developer velocity - XPVELOCITIES

The fields shown in the story summary can be customized via the ADDTLSTORYFIELDS preference variable.

Other tables available

This is a list of all the tables available. The names should be self-explanatory. Parameters are given in the form param="value". The first parameter, if present, is also the default parameter, and its name can be omitted.

Remember that the actual display of the hierarchy of activities can be configured by settings and may differ from the terminology reflected by these tags.

Time Tracking

Developers often work on more than one task at a time. We do want developers to keep their information up to date, which becomes tediuos if a developer works on many tasks. The following two tags simply this effort:

Below the estimate or timesheet table is a button that puts the table into edit mode and allows the user to enter estimates or update the information about effort spent for all open tasks at once.

Updates to the tasks as well as estimates can be given either in hours or days, as the user selects (however, the units must be consistent for the table). In addition, the user can select to have a report generated of the results of the update (this is helpful in case some of the topics are locked by some other user and could not be updated; also, such report gives the user a record of the information entered).

When updating assigned tasks the user can update the units spent on a task or the units remaining on the task or both. For updating the effort remaining, the user can select to do so in units of effort, or in percent done. For ongoing tasks (i.e., tasks that do not have a defined finish, only the effort spent can be updated.

When updating estimates, the user can provide an estimate of the effort to be performed on a task.

After filling in the desired information, the user must click the button below the table to submit the information to be added to the appropriate tasks. If the generate report options was selected, the report is presented.

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %EMPTYPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Plugin supporting light-weight project management.
• Plugin-specific settings
  • Set ADDTLSTORYFIELDS =
    • Additional fields of a story that should be displayed in story summaries.
  • Set ADDTLTIMESHEETFIELDS =
    • Additional fields of a story that should be displayed in timesheets.
  • Set STORYACCEPTEDINDICATION =
    • The story status which indicates that a story is accepted as completed.
  • Set ACCEPTANCELITERAL =
  • Set TEAMLABEL =
  • Set PROJECTLABEL =
  • Set SORT =
    • The field by which to sort stories in tables
• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

Getting Started with XpTracking

The distribution contains a set of template files in directory data/_default_XpTracker. The initial setup of a tracking web might be easiest if one starts from that example. Begin with GettingStarted.

When designing your own templates and tracking topics, there are a few rules that must be followed, lest the application will not work. (In the following, TEAMLABEL stands for what was configured to be the hierarchy for "Team", and PROJECTLABEL for "Project".)

• While templates instantiating the tracking topics may have any name, they must have attached the following forms:
  • Stories: StoryForm
  • Iterations: IterationForm
  • TEAMLABEL: TEAMLABELForm
• You can use arbitrary fields in forms defining the tracking topics, but the following fields must be present, as they are internally used:
  • Stories: Iteration, Submit Date, State, Story Summary
  • Iterations: TEAMLABEL, Start, End, Actual, Summary
  • TEAMLABEL: PROJECTLABEL
• The templates that can be chosen to instantiate tracking topics must be listed in the following topics:
  • Stories: StoryTemplateOptions
  • Iterations: IterationTemplateOptions
  • TEAMLABEL: TEAMLABELTemplateOptions
  • PROJECTLABEL: PROJECTLABELTemplateOptions

Due to a defect in Twiki 4.0 (fixed in TWiki 4.1) please copy the preference settings in the "XpTrackerPlugin" section of the WebPreferences sample topic into your the WebPrefernces topic of the tracking web.

To illustrate the customization of the work breakdown structure, in the sample tracking web the hierarchy of work is configured differently from the default.

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• This plugin works only with TWiki 4 and beyond.
• Download the ZIP file from the Plugin web (see below)
• Unzip YetAnotherXpTrackerPlugin.zip in your twiki installation directory. Content:

  data/TWiki/XpTrackerPlugin.txt
  lib/TWiki/Plugins/XpTrackerPlugin.pm
  lib/TWiki/Plugins/XpTrackerPlugin/Functions.pm
  lib/TWiki/Plugins/XpTrackerPlugin/HiddenTableDef.pm
  lib/TWiki/Plugins/XpTrackerPlugin/WebDB.pm
  templates/oopstimesheet.tmpl
  templates/oopstimesheetreport.tmpl
  lib/TWiki/Plugins/XpTrackerPlugin/build.pl
  lib/TWiki/Plugins/XpTrackerPlugin/Business.pm
  data/_default_XpTracker/PatternSkinTrackingviewTemplate.txt
  data/_default_XpTracker/PatternSkinTrackingeditTemplate.txt
  data/_default_XpTracker/PatternSkinTrackinggenericviewTemplate.txt
  data/_default_XpTracker/PatternSkinTrackinggenericeditTemplate.txt
  data/_default_XpTracker/IterationTemplate.txt
  data/_default_XpTracker/IterationTemplateOptions.txt
  data/_default_XpTracker/ProjectTemplate.txt
  data/_default_XpTracker/ProjectTemplateOptions.txt
  data/_default_XpTracker/StoryTemplate.txt
  data/_default_XpTracker/StoryTemplateOptions.txt
  data/_default_XpTracker/TeamTemplate.txt
  data/_default_XpTracker/TeamTemplateOptions.txt
  data/_default_XpTracker/TeamMembers.txt
  data/_default_XpTracker/IterationForm.txt
  data/_default_XpTracker/StoryForm.txt
  data/_default_XpTracker/ProjectForm.txt
  data/_default_XpTracker/TeamForm.txt
  data/_default_XpTracker/ProjectTopics.txt
  data/_default_XpTracker/TaskForm.txt
  data/_default_XpTracker/ATeamMember.txt
  data/_default_XpTracker/WebPreferences.txt
  data/_default_XpTracker/AllIterations.txt
  data/_default_XpTracker/GettingStarted.txt

• Download the other TWiki and CPAN modules that this plugin depends on.
• Alternatively, run YetAnotherXpTrackerPlugin_installer.pl to automatically check and install other TWiki modules that this module depends on. Make sure that the DBCacheContrib from TWiki:Plugins.YetAnotherDBCacheContrib is used.
• Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

Plugin Info

Plugin Author:	TWiki:Main.RichardBennett, TWiki:Main.MartinWatt, TWiki:Main.ThomasWeigert
Copyright:	© 2001-2006, TWiki:Main.RichardBennett, TWiki:Main.MartinWatt, TWiki:Main.ThomasWeigert
License:	GPL (GNU General Public License)
Plugin Version:	19 Dec 2006
19 Dec 2006:	Split small driver file from main code to speed loading.
15 Dec 2006:	Leverage the cache mechanism of TWiki:Plugins.YetAnotherDBCacheContrib to speed up expensive searches; small performance hit on very simple topics. Some refactoring.
1 Dec 2006:	Optional additional fields in timesheet. Do not generate timesheets, estimate tables, or load tables if not applicable.
25 Nov 2006:	Make topic sort configurable. Sort all iterations together in time sheet. Remove unneeded internally used fields. Add team argument to XPSHOWLOAD.
24 Nov 2006:	Allow creation of topics based on a base with sequence numbers affixed. Added XPCREATETOPIC tag. Use TWiki tables for formatting.
19 Nov 2006:	Cleaned up some of the table layout when empty cells are present. Apply rounding to numbers in generated tables.
31 Jul 2006:	Dakar port of branch developed and maintained by TWiki:Main.ThomasWeigert. Includes time tracking and recording capabilities built on ideas by TWiki:Main.ThomasEschner. Better task table control via TWiki:Plugins.EditHiddenTablePlugin
19 Nov 2002:	3.0 Updated version
16 Oct 2002:	2.0 New version of Plugin by TWiki:Main.MartinWatt
29 Jul 2002:	1.0 Initial version of Plugin by TWiki:Main.MartinWatt based on code by TWiki:Main.RichardBennett
Dependencies:	Name Version Description TWiki::Plugins::EditHiddenTablePlugin >=0 Required. Download and install from plugin library. TWiki::Plugins::DBCacheContrib >=0 Required. Download and install from plugin library. TWiki::Plugins::ControlsPlugin >=0 Required. Download and install from plugin library. HTTP::Date >=1 Required. Available from CPAN. Time::CTime >=1 Required. Available from CPAN.
Perl Version:	5.0
TWiki:Plugins/Benchmark:	GoodStyle xx%, FormattedSearch xx%, YetAnotherXpTrackerPlugin xx%
Plugin Home:	TWiki:Plugins/YetAnotherXpTrackerPlugin
Feedback:	TWiki:Plugins/YetAnotherXpTrackerPluginDev
Appraisal:	TWiki:Plugins/YetAnotherXpTrackerPluginAppraisal