Document the use of the GitHub Project feature

diff --git a/README.md b/README.md
index f0542ca..9ec348e 100644 (file)
--- a/README.md
+++ b/README.md
@@ -15,7 +15,13 @@ details, and is used in the standalone tools whilst also enabling integration
 into other code bases directly. The optimizer implementation resides in its
 own library, which depends on the core library.
 
-The interfaces are still under development, and are expected to change.
+The interfaces have stabilized:
+We don't anticipate making a breaking change for existing features.
+
+See [`projects.md`](projects.md) to see how we use the
+[GitHub Project
+feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
+to organize planned and in-progress work.
 
 SPIR-V is defined by the Khronos Group Inc.
 See the [SPIR-V Registry][spirv-registry] for the SPIR-V specification,
@@ -56,11 +62,15 @@ See [`syntax.md`](syntax.md) for the assembly language syntax.
 ### Validator
 
 *Warning:* The validator is incomplete.
-Check the [CHANGES](CHANGES) file for reports on progress.
+Check the [CHANGES](CHANGES) file for reports on completed work, and
+the [Validator
+sub-project](https://github.com/KhronosGroup/SPIRV-Tools/projects/1) for planned
+and in-progress work.
 
 *Note*: The validator checks some Universal Limits, from section 2.17 of the SPIR-V spec.
 The validator will fail on a module that exceeds those minimum upper bound limits.
-It is future work to parameterize the validator to allow larger
+It is [future work](https://github.com/KhronosGroup/SPIRV-Tools/projects/1#card-1052403)
+to parameterize the validator to allow larger
 limits accepted by a more than minimally capable SPIR-V consumer.
 
 

diff --git a/projects.md b/projects.md
new file mode 100644 (file)
index 0000000..8f7f0bc
--- /dev/null
+++ b/projects.md
@@ -0,0 +1,82 @@
+# Tracking SPIRV-Tools work with GitHub projects
+
+We are experimenting with using the [GitHub Project
+feature](https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/)
+to track progress toward large goals.
+
+For more on GitHub Projects in general, see:
+* [Introductory blog post](https://github.com/blog/2256-a-whole-new-github-universe-announcing-new-tools-forums-and-features)
+* [Introductory video](https://www.youtube.com/watch?v=C6MGKHkNtxU)
+
+The current SPIRV-Tools project list can be found at
+[https://github.com/KhronosGroup/SPIRV-Tools/projects](https://github.com/KhronosGroup/SPIRV-Tools/projects)
+
+## How we use a Project
+
+A GitHub Project is a set of work with an overall purpose, and
+consists of a collection of *Cards*.
+Each card is either a *Note* or a regular GitHub *Issue.*
+A Note can be converted to an Issue.
+
+In our projects, a card represents work, i.e. a change that can
+be applied to the repository.
+The work could be a feature, a bug to be fixed, documentation to be
+updated, etc.
+
+A project and its cards are used as a [Kanban
+board](https://en.wikipedia.org/wiki/Kanban_board), where cards progress
+through a workflow starting with ideas through to implementation and completion.
+
+In our usage, a *project manager* is someone who organizes the work.
+They manage the creation and movement of cards
+through the project workflow:
+* They create cards to capture ideas, or to decompose large ideas into smaller
+  ones.
+* They determine if the work for a card has been completed.
+* Normally they are the person (or persons) who can approve and merge a pull
+  request into the `master` branch.
+
+Our projects organize cards into the following columns:
+* `Ideas`: Work which could be done, captured either as Cards or Notes.
+  * A card in this column could be marked as a [PLACEHOLDER](#placeholders).
+* `Ready to start`: Issues which represent work we'd like to do, and which
+  are not blocked by other work.
+  * The issue should be narrow enough that it can usually be addressed by a
+    single pull request.
+  * We want these to be Issues (not Notes) so that someone can claim the work
+    by updating the Issue with their intent to do the work.
+    Once an Issue is claimed, the project manager moves the corresponding card
+    from `Ready to start` to `In progress`.
+* `In progress`: Issues which were in `Ready to start` but which have been
+  claimed by someone.
+* `Done`: Issues which have been resolved, by completing their work.
+  * The changes have been applied to the repository, typically by being pushed
+  into the `master` branch.
+  * Other kinds of work could update repository settings, for example.
+* `Rejected ideas`: Work which has been considered, but which we don't want
+  implemented.
+  * We keep rejected ideas so they are not proposed again. This serves
+    as a form of institutional memory.
+  * We should record why an idea is rejected. For this reason, a rejected
+    idea is likely to be an Issue which has been closed.
+
+## Prioritization
+
+We are considering prioritizing cards in the `Ideas` and `Ready to start`
+columns so that things that should be considered first float up to the top.
+
+Experience will tell us if we stick to that rule, and if it proves helpful.
+
+## Placeholders
+
+A *placeholder* is a Note or Issue that represents a possibly large amount
+of work that can be broadly defined but which may not have been broken down
+into small implementable pieces of work.
+
+Use a placeholder to capture a big idea, but without doing the upfront work
+to consider all the details of how it should be implemented.
+Over time, break off pieces of the placeholder into implementable Issues.
+Move those Issues into the `Ready to start` column when they become unblocked.
+
+We delete the placeholder when all its work has been decomposed into
+implementable cards.