Phlogiston/Configuring

Each separate Phlogiston report can be defined and configured in a number of ways, as dictated by the following three configuration files. See Phlogiston/Data Loading Model for an explanation of how these configuration files are used in context.

<prefix>_scope.py: Report configuration

Each team should use a separate Phlogiston report. Each report must have a configuration file, in the main phlogiston directory, named using the pattern: prefix_scope.py. The prefix should be a short (2-3 characters, hard limit of 6) unique identifier for this project.

Required Variables

The configuration file must contain these variables:

scope_title = Foo Widget Team

This is the report title displayed on the report page and charts. It should reflect the scope of tasks in the report, which is usually the name of the team responsible for the tasks.

Optional Variables

backlog_resolved_cutoff = [ 2015-01-01 | default ]

If set, the master burnup chart will show resolved tasks at zero prior to this date. This is to show progress from a recent point, such as the beginning of the quarter. Otherwise, a team that already has 500 resolved tasks at the beginning of the quarter will see their progress during the quarter rising from 500 (instead of 0), making it difficult to see recent progress. This does not affect per-tranche burnup charts. If a date is specified, the date is used. If the keyword default or True is specified, the beginning of the current quarter is used. If anything else is specified or this variable is not specified at all, no cutoff is applied.

default_points = 5

Default_points are assigned to all unpointed stories. If not present, unpointed stories remain unpointed.

retroactive_categories = True

If True, then after all tasks are categorized, Phlogiston will rewrite the history of all tasks so that they appear to always have been in whatever category they are in on the most recent day. For example, if task 100 was categorized as Category A on March 10th, and changed to Category B on April 15th, and the report is run on May 1, task 100 will appear to always have been in Category B. Defaults to false.

retroactive_points = True

If True, then Phlogiston will rewrite the history of all tasks so that they appear to always have had the point value that they have on the most recent day. Defaults to false.

show_count = False

show_points = False

These two variables determine which charts should be displayed, charts based on task count, charts based on task points, or both. Both default to True, so the configuration file should have neither (to get both count and points), or one of them set to False (to hide that type of chart).

start_date = 2015-01-01

This is the starting date for Phlogiston to import data from Phabricator. All data (tasks, transactions, projects, etc) before this date will be ignored. If not specified, this defaults to the beginning of the previous quarter (e.g., if today is April 5 2016, this will default to January 1 2016).

status_report_project = 1234

If specified, this is the Phabricator project Id that Phlogiston will use to select tasks for the Status Report. Even if specified, this will not be used if status_report_start is invalid or missing. Phlogiston only supports status reports for a single Phabricator project; if there are several to chose from, pick the project which contains "the tasks we are hoping to complete over this reporting period", which for Scrum will be the sprint backlog.

status_report_start = [ 2015-01-01 | 7 | True]

If specified, Phlogiston will use this information while creating the Status Report. If it is a valid date, that will be used. If it is an integer, that will be used as the number of days before the present (this will give poor results if underlying data is not current). If the keyword default or true is specified, it will use the start of the current quarter. For Scrum, put in the date the last scrum started. Otherwise, or if not specified, the Status Report will not be generated.

status_report_end = [ 2015-01-05 ]

If specified, Phlogiston will use this information while creating the Status Report. If it is a valid date, that will be used as the end date of the status report. If mising or invalid, the default is used instead. The default is the most recent date in the data.

<prefix>_recategorization.csv: Categories

The file prefix_recategorization.csv determines which tasks from Phabricator will be incorporated into the report and how they will be categorized. See col_recategorization.csv for an example.

Each row (except ProjectsByWildcard) in the file is one category. The category rules are applied in order, so that each task is categorized in the first category that it matches. Phlogiston reports on how it has interpreted the file (example). ProjectsByWildcard will generate multiple categories from one row.

The same rule cannot be used twice; this can happen inadvertantly when a wildcard creates a rule and then another entry creates the same rule. In this case, the second generated rule will be ignored. For this purpose, rules are the same if they have the same CategoryRule, ProjectID, and MatchString after wildcards are resolved.

CategoryRule

CategoryRule	how the CategoryRule works	ID	MatchString	Title	Display
ProjectByID	Matches all tasks that are members of the project specified by ID	ID to match	not used	The display title of the category, for use in charts and graphs.	True or False
ProjectByName	Matches all tasks that are members of the project specified by exact Phabricator name	not used	text for exact match with Phabricator project name
Intersection	Matches all tasks that are members of all of the specified project IDs for this row.	two IDs, separated by spaces	not used
ProjectColumn	Matches all tasks that are members of the specified project ID(s) and belong to a Phabricator column with the same name as the MatchString.	ID to match	text for substring match with Phabricator column names
ParentTask	Matches all tasks that are members of the specified project ID(s) AND are descendents (children, grandchildren, etc) of a task which is in the "Category" or "Goal" Phabricator projects (hard-coded to project IDs 1656 and 2169) AND whose title matches the MatchString. The tasks, all tasks in the family tree, and the category task must all be in the list of specified project IDs in this row. (e.g., if the category task is in project 'foo', and a child task is in project 'bar' and not in 'foo', and a grandchild task is in project 'foo', the grandchild task will not match under this rule.)	ID to match	text for match with Phabricator task name
ProjectsByWildcard	Finds all Phabricator projects whose names match the Matchstring, which is treated like a substring. E.g., "iOS-foobar" will match "iOS-foobar", "iOS-foobar-baz", and "foo-iOS-foobar", but not "iOS-foo-foobar". Each matching project is treated as if it were a separate "ProjectByName" category. Titles are copied from project names in Phabricator.	not used	text for substring match against Phabricator project names	not used

ID

For ProjectByID, ProjectColumn, or ParentTask, one valid Phabricator project IDs (not PHIDs). For Intersection, two Phabricator project IDs, separated by spaces. For ProjectByName or ProjectsByWildcard, leave blank.

MatchString

A character string to be used for matching as determined by the CategoryRule. Case-sensitive. For ProjectByID or Intersection, leave blank.

Title

The title that appears next to this category in charts and graphs. For ProjectsByWildcard, leave blank, because each match in the wildcard will get its own name automatically from its Phabricator project.

Display

Whether or not this category should be shown. Accepts any of three values, or none.

show (or no value): Include this category normally.
hide: Exclude this category from reports. It will still be included in the Completed Work report, and it can still be seen in the "show hidden" version of each report.
omit: Completely exclude this category from all reports.

Include_in_status

This is an obsolete setting (replaced by Display) that no longer has any effect.

Force_status

If set to the string resolved, all tasks in this category will be reported as if their status is 'resolved'. With any other setting, or if blank, there is no effect. The anticipated use case is for boards which have a "Done" column and put tasks into that column for some time before actually changing them to resolved.