diff options
authorMichael McCune <>2017-07-27 09:18:52 -0400
committerMichael McCune <>2017-08-03 15:29:06 -0400
commit6d3991fbfcd486deb2033a474d35a2273868e7f8 (patch)
parent12bf769d63859000d9c1ef92201924e1ee93d7dd (diff)
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
Notes (review): Code-Review+1: Chris Dent <> Code-Review+2: Ed Leafe <> Workflow+1: Ed Leafe <> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Thu, 17 Aug 2017 16:23:09 +0000 Reviewed-on: Project: openstack/api-wg Branch: refs/heads/master
2 files changed, 94 insertions, 2 deletions
diff --git a/doc/source/guidedreview.rst b/doc/source/guidedreview.rst
new file mode 100644
index 0000000..3411ede
--- /dev/null
+++ b/doc/source/guidedreview.rst
@@ -0,0 +1,84 @@
2Guided Review Process
5The API working group would like to increase the tools available to OpenStack
6project teams by defining a process and venue for conducting live face-to-face
7reviews. At a high level, these reviews are focused on the question "does my
8project align with the guidelines?" and are intended to be hosted by the
9working group at the PTG meetups.
11On a more concrete level, the working group expects that reviews which are
12directed towards specific areas, or problems within, an API will garner the
13best results (e.g. "Is using a PUT request for updating these resources
14appropriate?", "We are using GET requests to start server actions, is there a
15better alternative?").
17Ideal Candidates for Review
20It may be difficult if not impossible to review the entire API of a project in
21a session at the PTG. So here are some suggestions for selecting discussion
24Is there a part of your API that has generated some disagreement on your
25team? If so, that would be an excellent subject for discussion at the PTG.
27Are you unhappy with how some of your current API works? We could brainstorm
28ideas about making it more consistent and usable.
30Are you creating a new API? If you're starting a new project, or creating a
31new major version for your project, we can discuss what would be the most
32effective ways to approach it.
34How do I get my project reviewed?
37Here are some things you should prepare before approaching the API working
38group for a live review of your project:
401. Pick an area of your API to focus on (e.g. a specific resource type, an
41 interaction that is troublesome or endpoints that could use clarification).
432. Prepare a document describing the API in question, this could be free-form
44 or something more formal like an OpenAPI specification. This does not need
45 to be an expansive document, but should help drive the review conversation
46 and provide a reference for the reviewers to understand the flow of the API
47 in question.
49Then just show up to an API working group face-to-face session with your
50materials ready. Sending an email ahead of time will help to ensure that the
51group is ready for your review but is not strictly necessary.
53What should I expect from my review?
56The answer to this will vary depending on the nature of your request to the
57working group. You should expect to have clarification on the basic
58question of how close your API follows the working group's guidelines. But,
59the depth of your review will depend entirely on how big a request is made of
60the review group.
62The preparations that a project team makes before the review process will have
63the largest effect on the expected outcome. Teams that are more specific and
64focused with their requests to the review group will most likely harvest the
65greatest fruits from this process.
67When considering approaching the working group for a review, we encourage
68projects to identify areas of their APIs that could use clarification or have
69been problematic to the team. Project teams that have reviewed the API
70guidelines and have questions about specific areas of interest will find that
71their reviews will be more productive than open-ended questions which cover
72large portions of their API.
74After a review is completed, the API working group will archive the general
75details of the review (e.g. "Team <X> requested a review of API features <Y>
76and <Z>. It was agreed that actions <A>, <B> and <C> are the best path
77forward") and any artifacts that are generated during the process. This
78archive will exist in the same repository as the guidelines under a separate
79heading for reviews.
81Example Review
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 509fcc1..6d62c83 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -41,8 +41,7 @@
41Guidelines 41Guidelines
42---------- 42----------
43 43
44The following topics have separate doc pages that contain guidance on a 44The following topics are related to the working group and its processes:
45specific issue:
46 45
47.. toctree:: 46.. toctree::
48 :glob: 47 :glob:
@@ -51,4 +50,13 @@ specific issue:
51 process 50 process
52 template 51 template
53 liaisons 52 liaisons
53 guidedreview
55These topics are the API guidance approved by the OpenStack community
56and published by the working group:
58.. toctree::
59 :glob:
60 :maxdepth: 1
54 guidelines/* 62 guidelines/*