This repo contains the automations required for project "Project Tracking Template v01" and for other projects based on that template.
It also contains a copy of the documentation.
When you use that template to create a new project, you must clone this repo, point it to your new target project using Env vars, and configure the security tokens for your new project access (instructions below).
Workflow to trigger the script that updates the estimates for time / effort required for completing work items.
This workflow is automatically triggered at regular time intervals, and can also be manually started when needed.
The workflow uses GH secrets and variables to access configure the environment for the script it triggers.
Make sure to configure them accordingly if you close this repo.
Script to automatically compute time / effort estimates for work items (see below for details).
The project where the work items to be estimated3ed are located is passed by the invoking workflow via the environment.
Projects supported by update-project-item-estimation.js-script use two custom fields to describe the complexity of work items:
Size: an estimated range for time/effort required to complete a work item.Risk: a level of confidence that the size estimation is correct.
The custom field Days Estimate is a single number automatically computed based on those inputs. It is used for planning how long multiple sequential work items will take.
For that, Days Estimate-values of the respective work items are summed up. The result represents the estimated number of working days required to complete the work item(s), given the respective items' risk-confidence, and assuming full and exclusive concentration on that work.
See Project Tracking Template v01 for additional info.
The Days Estimate field represents working days required to complete the item with full and exclusive concentration.
In most cases it is advantageous to define work items so that they are worked on by a single person. Work involving multiple people should be represented by multiple dependent or related work items.
Days Estimate is auto-computed based on the Size and the Risk fields:
/ RiskSize(Dm - D days) |
Lowwell-understood(Dm + D) / 2 |
Midsome unknownsD |
Highrequires researchD × 1.5 |
Severe(*)open-endedD × 4 |
XS (1 ≤ day) |
0.5 | 1 | 1.5 | 4 |
S (1 - 3 days) |
2 | 3 | 4.5 | 12 |
M (3 - 5 days) |
4 | 5 | 7.5 | 20 |
L (1 - 2 weeks) |
7.5 | 10 | 15 | 40 |
XL(*) (2+ weeks) |
15 | 20 | 30 | 80 |
(*) XL-sized items and Severe-risk-level items are typically not well-enough understood to be included into timeline estimates with any reasonable degree of reliability. Such items should ideally be split into more concrete items. If you really need to use such items, apply estimate figures that are at least as large as stated in the table.
1. The size field defines the working days range estimate for the item:
- the base duration (D) is the upper end of the size field;
- the min duration (Dm) is the lower end of the size field.
Size |
D (base duration in working days) |
Dm (min duration in working days) |
|---|---|---|
XS (1 ≤ day) |
1 | 0.25 |
S (1 - 3 days) |
3 | 1 |
M (3 - 5 days) |
5 | 3 |
L (1 - 2 weeks) |
10 | 5 |
XL (2+ weeks) * |
20 | 10 |
* An XL-sized item indicates that it may be not well-enough understood to be included into timeline projections. Consider splitting it into smaller work items. If you really need to use XL-sized items, prefer using High or Severe risk levels to account for overlooked details.
2. Apply a risk modifier based on the Risk-field to transform the range estimated in step 1 into a single number representing an estimation for how many working days will actually be needed to complete the item (round up calculations to the nearest half-day):
Low: well-understood=> (Dm + D) / 2Mid: some unknowns=> DHigh: requires research=> D × 1.5Severe: open-ended=> D × 4 (*)
* Severe risk-level indicates that the item is likely not well-enough understood to be included into timeline projections. Consider splitting such work into smaller, better understood work items. But if you really need to use Severe-risk work items, assume D × 4 days (or more).
If you used the project template to create a new project and cloned this repo to enable the automations in your new project, you need to target the clone to your new project, and configure the security tokens so that the clone can access its new target.
If you project belongs to an organization you must configure a fine-grained personal access token (PAT). Fine-grained PATs are configured under:
User>Settings>Developer Settings>Personal Access Tokens>Fine-grained tokens
https://github.com/settings/personal-access-tokens
Create a new file-grained PAT. Settings:
Token name: a recommended pattern is TOKEN_REPO_NAME_TARGET_PROJECT_RW; e.g., the token for the upstream repo is called TOKEN_PROJECT_TRACKING_TEMPLATE_TARGET_PROJECT_RW, however, you can use any name you like.
Resource owner: The organization that owns the project.
Repository access: irrelevant since projects exist outside repos.
Permissions: select Projects with access set to Read and write.
(!) Once created, remember to write down the token value in a secure location. Once you navigate away form that screen, the value can no longer be retrieved.
If you project belongs to a you must configure a classic personal access token (PAT). Classic PATs are configured under:
User>Settings>Developer Settings>Personal Access Tokens>Tokens (classic)
https://github.com/settings/tokens
Create a new classic PAT. Settings:
Token name: a recommended pattern is TOKEN_REPO_NAME_TARGET_PROJECT_RW; e.g., the token for the upstream repo is called TOKEN_PROJECT_TRACKING_TEMPLATE_TARGET_PROJECT_RW, however, you can use any name you like.
Scopes: select projects with full control access.
(!) Once created, remember to write down the token value in a secure location. Once you navigate away form that screen, the value can no longer be retrieved.
The token belongs to a user and grants access either to projects within a specific organization or to all projects accessible to the user (see above). However, its value will be used by scripts in a repo. Next, you need to configure it for access to such scripts as a secure secret.
Secrets are configured under:
Repo>Settings>Secrets and variables>Actions
URL:https://github.com/repo_owner_org_or_user/repo_name/settings/secrets/actions
Tab:Secrets
Tap 'New repository secret'. Use the name TOKEN_TARGET_PROJECT_RW. You can use any other valid name, but you will need to adjust the secret reference in the workflow to match it.
Enter the exact value of the token you created earlier into the Secret field.
Remember to rotate the token and to update the secret value once the token expirtion date is reached.
There are some additional non-secret variables that need to be configured under:
Secrets are configured under:
Repo>Settings>Secrets and variables>Actions
URL:https://github.com/repo_owner_org_or_user/repo_name/settings/secrets/actions
Tab:Variables
Tap 'New repository variable'. to create a new clear-text variable. The following is required:
VAR_TARGET_PROJECT_OWNER_TYPE: Eitherorganizationoruser, depending on what type of entity owns the target project.VAR_TARGET_PROJECT_OWNER_NAME: A string denoting the name of the organization or the GitHub user who owns the target project.VAR_TARGET_PROJECT_NUMBER_ID: An integer denoting the project number within its owner container.
When you open the project in the browser, the URL looks like:
https://github.com/repo_owner_org_or_user/projects/N/
There, 'N' is the project number.