Merge "add a document for guided review process"
This commit is contained in:
commit
35c997e9ec
|
@ -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