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.

_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:. The  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:

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.

This is a comma-separated list of Phabricator project names. Spaces in names don't need to be quoted or escaped.

This is the starting date for Phlogiston to import data from Phabricator. All data (tasks, transactions, projects, etc) before this date will be ignored.

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

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.

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.

If set, burnup charts will show resolved tasks at zero on 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.

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).

_recategorization.csv: Categories
With the default configuration, Phlogiston will create one category for each combination of Project and Projectcolumn. This list of categories can be manually retitled, re-ordered, and consolidated with the optional file, which can be edited in a spreadsheet. See col_recategorization.csv for an example. If this file is not present, Phlogiston will generate a list of categories based on Phabricator projects and project columns, ordered alphabetically.

This is an integer sort sequence that determines the relative priority of categories and the order categories are displayed in the report. If a task matches two or more different categories, it will be counted in the category with the lowest sort_order.

If True, this category will be displayed in the report. If False, the category will be omitted from the Forecast and Burnup charts, but will be present in the "Unzoomed" versions of charts and in Velocity charts.

The display label of the category.

Optional Columns
Each row should have either,  or. If both t1/t2 and matchstring are specified, Phlogiston will ignore.

,
These are Phabricator project IDs. If present, Phabricator will categorize all tasks that belong to both of these projects in this category.

A Phabricator project ID can be found in its Phabricator profile URL. From a project workboard, click on the project name and icon in the top left corner to get to the profile.

Note that the Phabricator projects must also be added to the, by name, in order to be sure that all tasks belonging to those projects are included in the report. This will often lead to a substantial increase in the "uncategorized" category. For example, suppose t1 is "Team Foo FY2016Q4" and t2 is "Bar Feature", so that the reported category is all tasks for Bar Feature that are on the board for Team Foo this quarter. The  should therefore include "Team Foo FY2016Q4,Bar Feature", and the report will also include, as "uncategorized", all tasks in either of those projects but not both.

A text string used to categorize tasks. Phlogiston compares this to the raw category string of each task (which is a compound of the project title, project column, and titles of all parent tasks tagged with the category Phabricator project) to determine if the task belongs to this category. PhlogOther is a magic word that will match everything else.

_make_history.sql: Custom data processing
For each task, Phlogiston makes a text string combining everything that could be used to categorize it: the task title, the title of its project, the title of its project column, and the title of any Phabricator categories it belongs to.

(TODO: clarify: which project title if multiple projects? TODO - link to definition of Phlogiston category)

It also changes all stalled tasks to open, and deletes all duplicate, invalid, or declined tasks.

This is done by this file: https://github.com/wikimedia/phlogiston/blob/master/generic_make_history.sql. If your Phabricator projects do not follow these conventions, or have data by multiple configurations over time which you wish to preserve, you can write custom SQL code to replace this file. A file called, if present, will be run instead of generic_make_history.sql. See also ve_make_history.sql for an example.