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.

Proposed new categorization file
This is a proposed replacement design for the _recategorization.csv file. It would also eliminate the project_list variable from the _scope.py file. The design goals are: 1) reduced maintenance burden, 2) easy to understand and configure (more explicit, less side effects/indirect effects).

Each row 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.

CategoryRule
This determines how the category row is interpreted and applied. Must be one of these keywords:
 * ProjectByID
 * Matches all tasks are members of the specified project, which is specified by ID.
 * ProjectByName
 * Matches all tasks that are members of the specified project, which is specified by the exact Phabricator 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 auto-generated from project names in Phabricator, and any Title specified in the file is ignored.
 * Intersection
 * Matches all tasks that are members of all of the specified project IDs for this row.
 * 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.
 * MatchString is treated as a substring for column name matching, so "TR-0" will match "TR-0 Interrupt".
 * 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" Phabricator project 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.

ProjectID
One or more valid Phabricator project IDs (not PHIDs), separated by spaces.

MatchString
A character string to be used for matching as determined by the CategoryRule.

Title
The display title of the category, for use in charts and graphs.