1# Tracking SPIRV-Tools work with GitHub projects 2 3We are experimenting with using the [GitHub Project 4feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/) 5to track progress toward large goals. 6 7For 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 11The 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 16A GitHub Project is a set of work with an overall purpose, and 17consists of a collection of *Cards*. 18Each card is either a *Note* or a regular GitHub *Issue.* 19A Note can be converted to an Issue. 20 21In our projects, a card represents work, i.e. a change that can 22be applied to the repository. 23The work could be a feature, a bug to be fixed, documentation to be 24updated, etc. 25 26A project and its cards are used as a [Kanban 27board](https://en.wikipedia.org/wiki/Kanban_board), where cards progress 28through a workflow starting with ideas through to implementation and completion. 29 30In our usage, a *project manager* is someone who organizes the work. 31They manage the creation and movement of cards 32through 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 39Our 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 65We are considering prioritizing cards in the `Ideas` and `Ready to start` 66columns so that things that should be considered first float up to the top. 67 68Experience will tell us if we stick to that rule, and if it proves helpful. 69 70## Placeholders 71 72A *placeholder* is a Note or Issue that represents a possibly large amount 73of work that can be broadly defined but which may not have been broken down 74into small implementable pieces of work. 75 76Use a placeholder to capture a big idea, but without doing the upfront work 77to consider all the details of how it should be implemented. 78Over time, break off pieces of the placeholder into implementable Issues. 79Move those Issues into the `Ready to start` column when they become unblocked. 80 81We delete the placeholder when all its work has been decomposed into 82implementable cards. 83