Task representation

Tasks are represented by GitHub issues in a 1:1 correspondence.

This overall format is chosen to strike a reasonable balance of parser friendliness and human-readability.

Native properties

  • identifier is represented by the global GraphQL node ID (not the issue number, which is not unique across repositories - see e.g. the GitHub GraphQL docs for details).
  • state is represented by the Status field in the Github project board (for which automation may be set up to e.g. change the status when someone closes the issue).
  • title is represented by the issue title.
  • confirmed is represented by the closedAt field in the issue.
  • tags are represented by issue labels.

Other properties

Other properties and the definition of done are represented in the issue body, which must be formatted as follows (for example):

customer: @cwgoes
performer: @degregat
deadline: 2023-10-10
estimated: 4 hours
started: 2023-10-08
actual: 3 hours
completed: 2023-10-09
confirmed: null
dependencies:
- [ ] <task 1>
- [ ] <task 2>
- [ ] <...>
supersedes:
- <task 20>
---

< definition of done >

Properties are written at the top, in simple YAML syntax, and the definition of done is written in arbitrary text (Markdown formatted) at the bottom of the body. The property section and definition of done MUST be separated by '---' (triple dash). Properties which are not set MUST be set to null. All properties MUST be included.

Dependencies MUST be added with GitHub task syntax, e.g. - [ ] (issue link), such that they are annotated with dependency relationships in GitHub's database.

All date properties (deadline, started, completed) MUST be formatted as 'YYYY-MM-DD' (ISO 8601).

Duration properties (estimated and actual) MUST be specified in hours, days, weeks, or months, with a number prepended, e.g.:

  • 4 hours
  • 2 days
  • 1 week
  • 3 months

Durations MUST use a single level of precision, e.g 2 days, 4 hours is NOT a valid duration. This limitation is intentional, as we do not want to spend time negotiating time tracking minutea.

We permit a few slight deviations from normal YAML syntax:

  • Customer and performer may be specified using '@username' ('@' is not usually allowed by YAML parsers without quoting), e.g. '@cwgoes'.
  • '[ ]' and URLs are allowed in the list of dependencies (not usually allowed by YAML parsers without quoting).

Derived GitHub fields

The assignees field of GitHub issues MUST be set to the union of all customers and performers of the associated task.

Comments

Comments on the issues are synchronized with comments tracked in the task. The bot does not presently track edit history (just the current version).