| 1 |
# Tracking SPIRV-Tools work with GitHub projects |
| 2 |
|
| 3 |
We are experimenting with using the [GitHub Project |
| 4 |
feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/) |
| 5 |
to track progress toward large goals. |
| 6 |
|
| 7 |
For more on GitHub Projects in general, see: |
| 8 |
* [Introductory blog post](https://github.com/blog/2256-a-whole-new-github-universe-announcing-new-tools-forums-and-features) |
| 9 |
* [Introductory video](https://www.youtube.com/watch?v=C6MGKHkNtxU) |
| 10 |
|
| 11 |
The current SPIRV-Tools project list can be found at |
| 12 |
[https://github.com/KhronosGroup/SPIRV-Tools/projects](https://github.com/KhronosGroup/SPIRV-Tools/projects) |
| 13 |
|
| 14 |
## How we use a Project |
| 15 |
|
| 16 |
A GitHub Project is a set of work with an overall purpose, and |
| 17 |
consists of a collection of *Cards*. |
| 18 |
Each card is either a *Note* or a regular GitHub *Issue.* |
| 19 |
A Note can be converted to an Issue. |
| 20 |
|
| 21 |
In our projects, a card represents work, i.e. a change that can |
| 22 |
be applied to the repository. |
| 23 |
The work could be a feature, a bug to be fixed, documentation to be |
| 24 |
updated, etc. |
| 25 |
|
| 26 |
A project and its cards are used as a [Kanban |
| 27 |
board](https://en.wikipedia.org/wiki/Kanban_board), where cards progress |
| 28 |
through a workflow starting with ideas through to implementation and completion. |
| 29 |
|
| 30 |
In our usage, a *project manager* is someone who organizes the work. |
| 31 |
They manage the creation and movement of cards |
| 32 |
through the project workflow: |
| 33 |
* They create cards to capture ideas, or to decompose large ideas into smaller |
| 34 |
ones. |
| 35 |
* They determine if the work for a card has been completed. |
| 36 |
* Normally they are the person (or persons) who can approve and merge a pull |
| 37 |
request into the `master` branch. |
| 38 |
|
| 39 |
Our projects organize cards into the following columns: |
| 40 |
* `Ideas`: Work which could be done, captured either as Cards or Notes. |
| 41 |
* A card in this column could be marked as a [PLACEHOLDER](#placeholders). |
| 42 |
* `Ready to start`: Issues which represent work we'd like to do, and which |
| 43 |
are not blocked by other work. |
| 44 |
* The issue should be narrow enough that it can usually be addressed by a |
| 45 |
single pull request. |
| 46 |
* We want these to be Issues (not Notes) so that someone can claim the work |
| 47 |
by updating the Issue with their intent to do the work. |
| 48 |
Once an Issue is claimed, the project manager moves the corresponding card |
| 49 |
from `Ready to start` to `In progress`. |
| 50 |
* `In progress`: Issues which were in `Ready to start` but which have been |
| 51 |
claimed by someone. |
| 52 |
* `Done`: Issues which have been resolved, by completing their work. |
| 53 |
* The changes have been applied to the repository, typically by being pushed |
| 54 |
into the `master` branch. |
| 55 |
* Other kinds of work could update repository settings, for example. |
| 56 |
* `Rejected ideas`: Work which has been considered, but which we don't want |
| 57 |
implemented. |
| 58 |
* We keep rejected ideas so they are not proposed again. This serves |
| 59 |
as a form of institutional memory. |
| 60 |
* We should record why an idea is rejected. For this reason, a rejected |
| 61 |
idea is likely to be an Issue which has been closed. |
| 62 |
|
| 63 |
## Prioritization |
| 64 |
|
| 65 |
We are considering prioritizing cards in the `Ideas` and `Ready to start` |
| 66 |
columns so that things that should be considered first float up to the top. |
| 67 |
|
| 68 |
Experience will tell us if we stick to that rule, and if it proves helpful. |
| 69 |
|
| 70 |
## Placeholders |
| 71 |
|
| 72 |
A *placeholder* is a Note or Issue that represents a possibly large amount |
| 73 |
of work that can be broadly defined but which may not have been broken down |
| 74 |
into small implementable pieces of work. |
| 75 |
|
| 76 |
Use a placeholder to capture a big idea, but without doing the upfront work |
| 77 |
to consider all the details of how it should be implemented. |
| 78 |
Over time, break off pieces of the placeholder into implementable Issues. |
| 79 |
Move those Issues into the `Ready to start` column when they become unblocked. |
| 80 |
|
| 81 |
We delete the placeholder when all its work has been decomposed into |
| 82 |
implementable cards. |