Document the use of the GitHub Project feature
This commit is contained in:
Родитель
d004cd46db
Коммит
945e9fc4b4
16
README.md
16
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.
|
||||
|
||||
|
||||
|
|
|
@ -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.
|
Загрузка…
Ссылка в новой задаче