9fd03c71c7
This updates as many references to 'API-WG', 'API Working Group', etc., to reflect the name change to the API-SIG. Change-Id: I15ca0860c58bd7ba51f08dd39e551a774d7a060a
84 lines
3.7 KiB
ReStructuredText
84 lines
3.7 KiB
ReStructuredText
=====================
|
|
Guided Review Process
|
|
=====================
|
|
|
|
The API Special Interest 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 API Special Interest Group at the PTG meetups.
|
|
|
|
On a more concrete level, the API Special Interest 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 Special Interest 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
|
|
group. You should expect to have clarification on the basic question of how
|
|
close your API follows the API-SIG'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 API-SIG 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 Special Interest 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**
|