<commit_before># Evidence-Based Milestone Deadlines

Compute the deadline of a GitHub Milestone based on corrected issue
estimates.

* incurs a low-impact process on assignees
* puts estimates near all relevant details
* permits estimate revision as easily as providing the original estimate
* fosters single-source-of-truth for issue milestones and assignments
* adjusts the deadline when things are added, reopened, moved, or closed
* compensates for past estimate track-record
* does not increase the number of developer tools

## Estimating

An issue has an estimate if has a label such as:

    2 days
    14 hours
    1 week
    3 points

or more flexibly if any of its comments have a line of the format:

    estimated 2 days
    14hr estimate
    eta 0.9 week per mrmanager
    3 points

Comment estimates may be made by the assignee, other potential
assignee(s), or both.

## Computations

The Closed Issues Estimates *(CIE)* is the sum of estimates of closed
issues, grouped by an assignee.

Available Time *(AT)* is a function that computes the assignee
availability over a timespan, excluding their time off, holidays, or
other jobs.

For each assignee, the Velocity *(V)* is the ratio:

    V = CIE / AT(start..now)

A *V* of 100% means their estimates were accurate, whereas 200% means
they took half as long as estimated.

Open Issues Estimate *(OIE)* is the sum of estimates of open issues,
grouped by an assignee.

A Corrected Open Issues Estimate *(COIE)* is computed for each
assignee by:

    COIE = OIE * AT(now..COIE) / V

Issues with non-assignee estimates are potentially manually
(re)assignable, or Sheddable Issues *(SI)*.

## Reporting

The milestone's deadline is set to the last assignee's *COIE*.

The milestone's description is updated with an estimate report,
ordered by assignee's *COIE* (labeled `done`).  For estimate
calibration, the *OIE*, *AT(now..COIE)*, and *V* are revealed (labeled
`estimate`, `avail.`, and `velocity`).  For rebalancing, some *SI* IDs
are listed (labeled `sheddable`).

    | assignee |    done | estimate | avail. | velocity | sheddable |
    |----------|--------:|---------:|-------:|---------:|-----------|
    | @user1   | 10 days |  10 days |    88% |     110% | #239      |
    | @user2   | 68 days | 138 days |   100% |     200% | #226      |
    | @user3   |     TBD |          |        |          |           |

## Caveats

If either *CIE* or *AT(start..now)* are 0, *V* is 100%.  This
serves estimating before commencing work.

If any open issue for the milestone does not have an estimate, or if
the milestone has a prior open milestone without a deadline, the
milestone deadline is not computable.  The deadline is thus unset.

If the open issue is assigned but without an estimate, the assignee's
*COIE* is `TBD`.  This calls out those who have not provided
estimates.
<commit_msg>rendered example table<commit_after># Evidence-Based Milestone Deadlines

Compute the deadline of a GitHub Milestone based on corrected issue
estimates.

* incurs a low-impact process on assignees
* puts estimates near all relevant details
* permits estimate revision as easily as providing the original estimate
* fosters single-source-of-truth for issue milestones and assignments
* adjusts the deadline when things are added, reopened, moved, or closed
* compensates for past estimate track-record
* does not increase the number of developer tools

## Estimating

An issue has an estimate if has a label such as:

    2 days
    14 hours
    1 week
    3 points

or more flexibly if any of its comments have a line of the format:

    estimated 2 days
    14hr estimate
    eta 0.9 week per mrmanager
    3 points

Comment estimates may be made by the assignee, other potential
assignee(s), or both.

## Computations

The Closed Issues Estimates *(CIE)* is the sum of estimates of closed
issues, grouped by an assignee.

Available Time *(AT)* is a function that computes the assignee
availability over a timespan, excluding their time off, holidays, or
other jobs.

For each assignee, the Velocity *(V)* is the ratio:

    V = CIE / AT(start..now)

A *V* of 100% means their estimates were accurate, whereas 200% means
they took half as long as estimated.

Open Issues Estimate *(OIE)* is the sum of estimates of open issues,
grouped by an assignee.

A Corrected Open Issues Estimate *(COIE)* is computed for each
assignee by:

    COIE = OIE * AT(now..COIE) / V

Issues with non-assignee estimates are potentially manually
(re)assignable, or Sheddable Issues *(SI)*.

## Reporting

The milestone's deadline is set to the last assignee's *COIE*.

The milestone's description is updated with an estimate report,
ordered by assignee's *COIE* (labeled `done`).  For estimate
calibration, the *OIE*, *AT(now..COIE)*, and *V* are revealed (labeled
`estimate`, `avail.`, and `velocity`).  For rebalancing, some *SI* IDs
are listed (labeled `sheddable`).

    | assignee |    done | estimate | avail. | velocity | sheddable |
    |----------|--------:|---------:|-------:|---------:|-----------|
    | @user1   | 10 days |  10 days |    88% |     110% | #239      |
    | @user2   | 68 days | 138 days |   100% |     200% | #226      |
    | @user3   |     TBD |          |        |          |           |

which renders like:

| assignee    |    done | estimate | avail. | velocity | sheddable |
|-------------|--------:|---------:|-------:|---------:|-----------|
| [@user1](#) | 10 days |  10 days |    88% |     110% | [#239](#) |
| [@user2](#) | 68 days | 138 days |   100% |     200% | [#226](#) |
| [@user3](#) |     TBD |          |        |          |           |

## Caveats

If either *CIE* or *AT(start..now)* are 0, *V* is 100%.  This
serves estimating before commencing work.

If any open issue for the milestone does not have an estimate, or if
the milestone has a prior open milestone without a deadline, the
milestone deadline is not computable.  The deadline is thus unset.

If the open issue is assigned but without an estimate, the assignee's
*COIE* is `TBD`.  This calls out those who have not provided
estimates.

{'fraction_non_alphanumeric': 0.11140322050607952, 'fraction_numerical': 0.021196187972395662, 'mean_word_length': 2.8969270166453267, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4240377', 'n_tokens_mistral': 1942, 'n_tokens_neox': 1730, 'n_words': 815}