add a document for guided review process

This change adds the first draft revision of the guided review process
document. It also slightly reorganizes the table of contents links for
guidance on the index page to make it clear which guidance is for API
issues and which are for working group process issues.

Change-Id: Ifd7c7dce7f61bc57555e3bd2abac2703c1c7b6a3
This commit is contained in:
Michael McCune 2017-07-27 09:18:52 -04:00
parent 12bf769d63
commit 6d3991fbfc
2 changed files with 94 additions and 2 deletions

View File

@ -0,0 +1,84 @@
=====================
Guided Review Process
=====================
The API working group would like to increase the tools available to OpenStack
project teams by defining a process and venue for conducting live face-to-face
reviews. At a high level, these reviews are focused on the question "does my
project align with the guidelines?" and are intended to be hosted by the
working group at the PTG meetups.
On a more concrete level, the working group expects that reviews which are
directed towards specific areas, or problems within, an API will garner the
best results (e.g. "Is using a PUT request for updating these resources
appropriate?", "We are using GET requests to start server actions, is there a
better alternative?").
Ideal Candidates for Review
---------------------------
It may be difficult if not impossible to review the entire API of a project in
a session at the PTG. So here are some suggestions for selecting discussion
topics:
Is there a part of your API that has generated some disagreement on your
team? If so, that would be an excellent subject for discussion at the PTG.
Are you unhappy with how some of your current API works? We could brainstorm
ideas about making it more consistent and usable.
Are you creating a new API? If you're starting a new project, or creating a
new major version for your project, we can discuss what would be the most
effective ways to approach it.
How do I get my project reviewed?
---------------------------------
Here are some things you should prepare before approaching the API working
group for a live review of your project:
1. Pick an area of your API to focus on (e.g. a specific resource type, an
interaction that is troublesome or endpoints that could use clarification).
2. Prepare a document describing the API in question, this could be free-form
or something more formal like an OpenAPI specification. This does not need
to be an expansive document, but should help drive the review conversation
and provide a reference for the reviewers to understand the flow of the API
in question.
Then just show up to an API working group face-to-face session with your
materials ready. Sending an email ahead of time will help to ensure that the
group is ready for your review but is not strictly necessary.
What should I expect from my review?
------------------------------------
The answer to this will vary depending on the nature of your request to the
working group. You should expect to have clarification on the basic
question of how close your API follows the working group's guidelines. But,
the depth of your review will depend entirely on how big a request is made of
the review group.
The preparations that a project team makes before the review process will have
the largest effect on the expected outcome. Teams that are more specific and
focused with their requests to the review group will most likely harvest the
greatest fruits from this process.
When considering approaching the working group for a review, we encourage
projects to identify areas of their APIs that could use clarification or have
been problematic to the team. Project teams that have reviewed the API
guidelines and have questions about specific areas of interest will find that
their reviews will be more productive than open-ended questions which cover
large portions of their API.
After a review is completed, the API working group will archive the general
details of the review (e.g. "Team <X> requested a review of API features <Y>
and <Z>. It was agreed that actions <A>, <B> and <C> are the best path
forward") and any artifacts that are generated during the process. This
archive will exist in the same repository as the guidelines under a separate
heading for reviews.
Example Review
--------------
**TODO**

View File

@ -41,8 +41,7 @@ http://docs.openstack.org/infra/manual/developers.html
Guidelines
----------
The following topics have separate doc pages that contain guidance on a
specific issue:
The following topics are related to the working group and its processes:
.. toctree::
:glob:
@ -51,4 +50,13 @@ specific issue:
process
template
liaisons
guidedreview
These topics are the API guidance approved by the OpenStack community
and published by the working group:
.. toctree::
:glob:
:maxdepth: 1
guidelines/*