Phlogiston/Configuring
 | This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on the information here being up-to-date. |
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
[edit]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
[edit]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
[edit]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
[edit]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
[edit]| 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
|
ID to match | text for match with Phabricator task name | ||
| ProjectsByWildcard |
|
not used | text for substring match against Phabricator project names | not used |
ID
[edit]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
[edit]A character string to be used for matching as determined by the CategoryRule. Case-sensitive. For ProjectByID or Intersection, leave blank.
Title
[edit]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
[edit]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
[edit]This is an obsolete setting (replaced by Display) that no longer has any effect.
Force_status
[edit]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.