Horizontal issue tracker: How to

The horizontal tracker pages provide one particular view into the data which is maintained in the tracker repository of each Horizontal Group. That view tends to helpful for getting an overview of unresolved issues, arranged by specification. Issues can have either a tracker label or a needs-resolution label: this indicates whether or not a resolution is required prior to a spec transition.

The other colours on the interface conform to a traffic-light system, although the actual use of those labels may vary from group to group.

The horizontal group may use other labels, some of which are listed below, to manage the items in the tracker repository, but these don't show up on the tracker boards.

Working with labels

The following provides hints for staff and chairs of horizontal groups. (See a description of how labels work from the point of view of spec WG personnel.)

The table describes a set of scenarios, and provides a set of fairly detailed information about what to do given that scenario.

Someone adds a *-tracker label to an issue in a WG repo.
  1. The tooling creates a tracker issue in the HR repo, and applies the following labels: pending, s:xxx, tracker.
  2. The HR group looks at the issue and decides whether it should continue with the tracker label.
  3. If the HR group wants to see a particular resolution to the issue: they indicate that desired resolution in the WG repo, and change the labels in both repos to *-needs-resolution.
  4. The HR group removes the pending label from the issue in the HR repo.
A reviewer comes across an issue during a review and wants to raise it.
  1. Create a new issue in the HR tracker repo, describing the issue. (There should be some boilerplate instructions.)
  2. Apply a pending label.
  3. Apply a s:xxx label with the short name for the spec.
  4. Ask the group to review the proposed comment.

(See an i18n example of boilerplate for new issue.)
The HR group has reviewed & approved a new comment.
  1. Create a new issue in the WG repo, based on the text reviewed by the HR WG.
  2. Add a *-needs-resolution label to both the WG repo and HR repo.
  3. Remove the pending label in the HR repo.

  4. Reduce the comment text in the HR repo to:

    **This is a tracker issue.** Only discuss things here if they are i18n WG internal meta-discussions about the issue. **Contribute to the actual discussion at the following link:**

    ยง link_to_issue_raised

  5. Replace link_to_issue_raised with a link to the new WG issue.
The HR group is satisfied by the resolution of an issue in the WG repo.
  1. The HR group indicates that it is satisfied in the issue in the WG repo.
  2. The HR group closes the issue in the HR repo.

Note that no labels need to be changed or removed. Keeping the needs-resolution or tracker label may be useful later for post-mortems, or for issues that get reopened later, etc.
An issue that needs resolution in the WG repo is closed, but hasn't been closed in the HR repo.
  1. The tooling will add a Close? label to the issue in the HR repo, signalling that the HR group should consider whether the issue is resolved.
  2. The HR group discusses the current status.
  3. If the issue is still unresolved: the HR group removes the Close? label and takes whatever action is needed in the issue in the WG repo.
  4. If the issue is resolved: the HR group closes the issue in the HR repo, and indicates in the WG repo that they are satisfied/no longer tracking/etc. (No need to remove Close? label, but ok if you want to.)
A tracker issue in the WG repo is closed, but hasn't been closed in the HR repo.
  1. The tooling will add a Close? label to the issue in the HR repo, signalling that the HR group should consider whether to stop tracking that issue.
  2. The HR group discusses the current status.
  3. If uncontroversial: the HR group closes the issue in the HR repo at their leisure. (No need to remove Close? label, but ok if you want to.)
  4. If the resolution of the WG issue is problematic: the HR group may decide to reopen the issue in the WG repo with a comment indicating their concerns. In this case, it would probably be appropriate to change the *-tracker label to a *-needs-resolution label in both the WG and HR repos.
The spec WG wants to postpone resolution of an issue until the next version.

If the HR group agrees:

  1. The HR group closes the issue in the HR repo, but adds a Recycle label.
  2. When the next version comes online, the HR group filters the GH repo to find issues with the Recycle label for that spec, removes the Recycle label, and opens the issues.
  3. The HR group reopens or creates new issues in the WG repo.
The HR group decides to change a *-tracker label to *-needs-resolution.
  1. Make a comment in the WG repo issue to indicate what resolution you are looking for.
  2. Change the *-tracker label to *-needs-resolution in both the WG and HR repos.
The HR group decides to change a *-needs-resolution issue to *-tracker.
  1. Change the *-needs-resolution label to *-tracker in both the WG and HR repos.
The spec WG explicitly asks the HR group to provide specific advice for an issue.

[Optional] This describes what the i18n HG does.

  1. Add the Advice requested label to the issue in the HR repo.
  2. The HR group discusses and/or assigns someone to respond to the spec WG's request as a priority.
  3. Remove the Advice requested label after the intervention (since that label is intended to catch the eye and help prioritise treatment of issues).

There is no tooling at the moment to highlight such direct appeals for help, however, if the HR group is following their notifications and reading the new comments added to the WG repo they should spot these requests.
Someone in the HR group realises that an issue that has been labelled in a WG repo needs urgent attention.

[Optional] This describes what the i18n HG does.

  1. Add the Needs attention label to the issue in the HR repo.
  2. The HR group discusses and/or assigns someone to respond to the spec WG's request as a priority.
  3. Remove the Needs attention label after the intervention (since that label is intended to catch the eye and help prioritise treatment of issues).
The tooling created a tracker issue in the HR repo but there was no s:xxx label. This means that the issues don't show up in the 'board'.

This sometimes happens because the tool fails to find the shortname for a repo like CSS that has many shortnames. It may also happen if the thing being tracked doesn't have a shortname, such as webex implementations, or CG documents that don't yet have shortnames.

  1. The new issue will come into the HR repo with a pending label, indicating that you need to check is has the appropriate additional labels. While doing that, simply invent a s:xxx label in GitHub and assign it to the relevant issue(s) (eg. s:webex). The label doesn't have to represent an actual shortname for the board to pick it up. The board will automatically display issues with that label in a new section.
  2. At some point in the future you may need to change the s:xxx label (eg. if a document does finally get a shortname, and it's different to what you were using). That's no problem. Just rename the existing label using the GH interface, and the board will continue to create a section with that name and group all the relevant issues therein.
A spec WG requests a transition call.

The spec WG should have checked with the HR group that all issues with a *-needs-resolution label have been resolved, and each issue should describe that resolution.

The spec WG does NOT need to reach agreement with the HR group for issues that are only marked with a *-tracker label.

Prior to the transition call, the Director will run a tool to check whether the HR group repos have unclosed issues with the *-needs-resolution label. If there are some, they will have to take a decision about whether or not the lack of resolution will prevent the spec from progressing to the next stage. This may require consultation with the HR group.