Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

GitLab issue tracking

Context

Our policies on using GitLab for issue tracking were previously buried in TPA-RFC-5: GitLab migration. Everyone on GitLab has switched from using labels to using Work Item Status to triage issues, and we need to follow suite.

It feels better to write a new ADR for this than to try to retrofit this in the old RFC.

Decision

We use GitLab for issue tracking, "work item statuses" for sorting issues and Kanban boards to for triage. Roadmaps are now in "epics".

Consequences

A couple of migration tasks will happen over a couple of days, detailed in tpo/tpa/team#42451.

This is mostly a cosmetic change: we were previously using ~Roadmap labels and now we'll use the "work item status" field instead.

Epics, instead of wiki pages, should be used to plan long-term roadmaps. The issue description should be treated as a wiki page that has a overall logical view of the roadmap. Issues, sometimes multiple issues or even sub-epics, should be created for each project.

A variation of this ADR will be sent to the team to inform them of the change.

More Information

The Kanban mechanism might require a little more information. We use the GitLab issue boards as Kanban boards to triage issues.

The Work Item Status values currently defined are:

  • Needs Triage
  • Not Scheduled
  • Backlog
  • Next
  • Doing
  • Done
  • Won't do
  • Duplicate

Each of those is a separate column in the board, except "Done", "Won't do" and "Duplicate" which are regrouped in a single column. Tickets flow from top to bottom in the list (which is arranged left to right in the boards).

Steps can be skipped entirely, for example an issue can easily go directly from Needs Triage to Done (which is what closing an issue will do), or from Needs Triage to Doing (which should be done explicitly).

Bot policies

There is a bot named "triage-bot" that goes through our issues and flags problematic ones. It implement the current policies, which will be updated to match the new status field:

  1. warn-unlabeled:
    • warn about issues without a label for 5 days: will now warn (and label as ~Stale) about issues in "Needs Triage" for the same delay
    • move unlabeled, stale issues to icebox after 2 days (or 7 days total): similar but with "Needs Triage" and "Not Scheduled"
  2. stale:
    • warn about issues in "Needs Review, Needs Information, Roadmap::Next, Roadmap::Doing" without activity for 2 weeks: same about "Next" and "Doing" statuses, no special handling of "Needs review" and "Needs information" anymore
    • "freeze ancient issues"; move two weeks old "Needs information" issues to icebox: will be removed
  3. unassigned-next-doing:
    • automatically assigns issues in Next or Doing to a random person, will be ported to the new statuses
  4. stale-mrs: unchanged
  5. mr-random-assign-team-member: unchanged

Mapping from old labels

This is the mapping with the old roadmap labels:

  • Open (unlabeled): Needs Triage
  • ~Roadmap::Icebox: Not Scheduled
  • ~Roadmap::Future: Not Scheduled
  • ~Roadmap::Backlog: Backlog
  • ~Roadmap::Next: Next
  • ~Roadmap::Doing: Doing
  • Closed (possibly unlabeled): Done, Won't do, or Duplicate
  • ~"Needs Information": Next, label kept
  • ~"Needs Review": Next, label deprecated

In other words, instead of "moving" an issue from (say) "Doing" to "Needs information", one would now move it to "Next" and add the "Needs information" label.

All existing labels will be untouched but are deprecated. It is assumed their use will slowly stop and disappear as we close issues.

Documentation and wikis

Note that this decision explicitly does not cover documentation. TPA-RFC-5: GitLab migration was designating GitLab wikis as our documentation tool but a separate conversation about this is happening in TPA-RFC-48 and is now out of scope here.

Note about proprietary software

The GitLab Work Item Status and epics are proprietary features available only GitLab Premium and Ultimate.

Those changes are part of the GitLab Ultimate rollout decided by the directors of TPI. That specific decision was not made by the TPA team lead, which instead believes that free software needs free tools.

Metadata

  • status: approved
  • decision-date: 2026-01-14
  • decision-makers: TPA team lead
  • consulted: team, informally, over IRC
  • informed: tpa-team@lists.torproject.org
  • forum-url: https://gitlab.torproject.org/tpo/team/-/issues/419