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:
parent
12bf769d63
commit
6d3991fbfc
|
@ -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**
|
|
@ -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/*
|
||||
|
|
Loading…
Reference in New Issue