Workflow

This document explains the workflow of developing the API, how it's tracked, and what stages a change needs to go through before it can be considered done.

We use a Github project for tracking the status of features and fixes. Every non-trivial change should have a single tracking issue in the gpuweb repository, which can link to other issues and PRs. Tracking has to go through the following steps:

1. Needs Investigation/Proposal or Revision - The change is on our radar. If work has been started, the tracking issue gets assigned to a "champion", who will drive the discussion. We may be investigating the differences between the native APIs, evaluating the portability and security constraints as well as the value of a change. An investigation-labelled issue can be linked with the main one.
2. Needs Discussion - An investigation or proposal has been written, and the community group needs to discuss it and come to a resolution (accepted, needs revision, etc.)
3. Specification - We have accepted one of the proposals and have a rough idea of how the change would be specified and tested. When an issue enters this stage, the assignee is potentially cleared, unless the same person wants to drive it through. Once it's picked up, the assignee works on formally describing the change in the specification. A gpuweb project PR may be linked with the main issue.
4. Needs CTS Issue - We have landed the specification changes. A "draft" issue needs to be filed in the CTS project tracker reflecting the test changes that need to occur.
5. Specification Done - A change has been either rejected, or fully implemented in the specification. Tests may not be implemented or even planned yet, but are reflected in the CTS issue tracker in enough detail (with any necessary TODOs) to ensure the tests are implemented fully, later on.

Linking PRs to the project

Pull requests shouldn't be added as cards to the project. Instead, they should link back to gpuweb issues which are tracked in the project. Note: Don't use "closes #xxx" or "fixes #xxx" in the PR if "#xxx" is a tracking issue. Instead, move the tracking issue manually between columns of the tracker. (This may be automated in the future.)

Reading the project tracker

A cursory look at the project can give us a rough idea on what the issues are currently in the works, and which ones need attention.

On each card on the tracker, an icon appears on the bottom-right of the card if it is assigned. If no icon appears, the task (of completing the current column for this card) is currently unassigned. These issues are up for grabs.

In order to get a list of all project issues that are waiting to be picked up, use this issue query. It shows all unassigned tracking issues (regardless of column).