Calories, Increments and Lines
Calories and Increments are Q247's own units for measuring development effort. They are calculated from the content and size of the recorded changes.
Increment
An Increment is one recorded change, in one of five forms, depending on the source:
- Git: commit, push, pull request.
- Jira: ticket.
- Confluence: page.
What exactly counts as an increment in a given place in the application depends on the selected Calories Type:
- Total: commits, pushes, pull requests, Jira tickets, and Confluence pages together.
- Coding: only increments from a repository.
- Documentation: only Jira tickets and Confluence pages.
Calories
Calories measure the effort put into a change. They are made up of two factors: the size of the change (that is, Lines) and the diversity of its content. The larger the change and the more diverse the content, the more Calories.
The diversity of the content is measured with Shannon entropy, a measure from information theory that says how many bits of information the average character of the text carries. Repetitive, predictable text has low entropy, and diverse text has high entropy.
Entropy is calculated from several pieces of text related to the change (among others, the diff content, the commit message, the linked ticket) and combined into a single result. A plain push with no content differences (for example, creating a tag, with no diff to measure) always counts as a fixed, small value, regardless of Lines.
The same formula is applied to every change, regardless of the programming language and file type.
Excluding files from the calculation
Calories are calculated separately for each file in a commit, so files that distort the picture of the work can be excluded from the calculation. This is what File Pattern Exclusions in the organization's Configuration are for: a list of glob patterns (*, **, ?, case-insensitive) that the administrator maintains once for the whole organization. A file matching any of the patterns is skipped when calculating Calories and Lines, and typical entries on this list are lockfiles, dependency directories, and automatically generated code, for example **/package-lock.json or **/node_modules/**.
Changing this list also recalculates historical data, so adding a pattern lowers Calories for periods before the change as well.
Besides file patterns, three other mechanisms are at work. Q247 automatically skips commits that revert another commit or repeat one already counted (cherry-pick, rebase), which Commit exclusion describes. A project manager or team manager can exclude a single commit from the project, team, or participant view. An administrator can additionally set a Calories threshold above which a single increment is hidden from the detail lists, which is useful when importing a large repository as a one-off.
Calories are the most commonly used measure in Q247. Further indicators are built on them, including Effort from the Work Dynamics Indexes and Grade.
Calories are not an assessment of code quality or task difficulty. A high score does not mean the change was good, and a low one does not mean it was bad.
Lines
The number of changed lines of code, added and removed together, in an increment. This is a raw measure of the size of the change, with no adjustment.
Variants and aggregation levels
All three measures aggregate the same way. A participant's value for a period is the sum of their increments, and the value of a project or team is the sum of the values of its participants. The same commit therefore counts at the same time toward the result of its author, their team, and the project the repository belongs to.
Each of the measures comes in several variants, depending on the level and the time frame:
| Variant | Participant | Project / team |
|---|---|---|
| Sum for the period | Calories (total), Increments (total), Lines (total) | the same three columns, summed across participants |
| Daily average | Daily Calories, Daily Increments, Daily Lines | Daily Calories / Person, Daily Increments / Person, Daily Lines / Person |
| Per increment | Calories / Increment | Calories / Increment |
The daily value for a participant is the sum divided by the number of calendar days in the period. For a project or team, the daily value per person additionally divides this by Effective Team Capacity, which accounts for the fact that not everyone worked the whole period. Dividing by the raw number of participants would understate the result of a team that someone joined halfway through the period.
The "per increment" variant is available only for Calories, because it comes from dividing Calories by Increments. It shows the average size of a single change: a high value means rare, large commits, and a low value means frequent, small ones.
The value at the project or team level is the sum of those same individual participant values, and in the "per person" variants that sum divided by Effective Team Capacity. Looking at the participant table of a given project, it is worth remembering that several people with very different contributions can produce the same, "average" team result, so when interpreting a team value it is good to go one level down, to the participant table of that team or project, and check whether the result is spread evenly or generated mainly by 1-2 people.
See also
- Calories Type: the Total / Coding / Documentation filter, deciding which increments count
- Overview, Project, Team, Participant: the views these metrics appear on