What is a tracking issue?

A tracking issue is a GitHub issue that captures the planned and on-going work of a team's milestone, project, RFC, goal or anything else of the sort. This artifact is a medium used for planning, progress check-ins and stakeholder communication. You can take a look at examples of open tracking issues to get a sense of what they look like.

Note that this is an optional process; some teams use tracking issues and some teams do not. For those that do they will follow the procedures below.

Creating a new tracking issue

  1. Create a new GitHub issue with the tracking issue template.
  2. Give it the "$THING_BEING_TRACKED: Tracking issue" title.
  3. Assign it to the right milestone, creating such milestone if it doesn't yet exist.
    1. Note that the right milestone may be no milestone at all. Check with your team if you are unsure.
  4. Ensure the tracking label is set as well as the other labels you want to track. Issues and pull requests with those labels will show up in the tracking issue.

Updating an existing issue

If you want to convert an existing issue into a tracking issue:

  1. Add the tracking label.
  2. Update the title by appending ": Tracking issue".
  3. Add the following code to the bottom of the issue.
### Tracked issues<!-- BEGIN WORK --><!-- END WORK -->#### Legend- 👩 Customer issue
- 🐛 Bug
- 🧶 Technical debt
- 🎩 Quality of life
- 🛠️ [Roadmap](<https://handbook.sourcegraph.com/departments/product-engineering/process/planning-process#roadmap>)- 🕵️ [Spike](<https://en.wikipedia.org/wiki/Spike_(software_development)>)
- 🔒 Security issue
- 🙆 Stretch goal

Populating and maintaining a tracking issue

An open tracking issue is populated and kept up to date with the GitHub issues and pull requests labeled the same as the tracking issue (minus the tracking label) that belong to any repositories of the sourcegraph organization. Optionally, a milestone can also be set. If a milestone is set, all linked issues must also belong to the same milestone. The tracking issue will be updated as these issues and pull requests are opened, changed, closed, merged, etc.

This is done automatically by the tracking-issue tool which runs in response to GitHub issue events happening in https://github.com/sourcegraph/sourcegraph.

Rendering

There are a number of ways to affect how the workload section of a tracking issue is rendered.

Visibility