Change API-WG to API-SIG
This updates as many references to 'API-WG', 'API Working Group', etc., to reflect the name change to the API-SIG. Change-Id: I15ca0860c58bd7ba51f08dd39e551a774d7a060a
This commit is contained in:
parent
8cf00fde96
commit
9fd03c71c7
10
README.rst
10
README.rst
|
@ -2,12 +2,12 @@
|
|||
README
|
||||
======
|
||||
|
||||
Openstack API Working Group documents
|
||||
-------------------------------------
|
||||
Openstack API Special Interest Group documents
|
||||
----------------------------------------------
|
||||
|
||||
This repository contains documents from the OpenStack API working group,
|
||||
including guidelines and proposed rules concerning API consistency, naming
|
||||
conventions, and best practice recommendations. The published
|
||||
This repository contains documents from the OpenStack API Special Interest
|
||||
Group, including guidelines and proposed rules concerning API consistency,
|
||||
naming conventions, and best practice recommendations. The published
|
||||
information can be found at `specs.openstack.org
|
||||
<http://specs.openstack.org/openstack/api-wg/>`_.
|
||||
|
||||
|
|
|
@ -35,7 +35,7 @@ extensions = ['sphinx.ext.autodoc',
|
|||
|
||||
# Feed configuration for yasfb
|
||||
feed_base_url = 'http://specs.openstack.org/openstack/api-wg'
|
||||
feed_author = 'OpenStack API Working Group'
|
||||
feed_author = 'OpenStack API Special Interest Group'
|
||||
|
||||
todo_include_todos = True
|
||||
|
||||
|
@ -52,8 +52,8 @@ source_suffix = '.rst'
|
|||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'API Working Group'
|
||||
copyright = u'%s, OpenStack API Working Group Team' % datetime.date.today().year
|
||||
project = u'API Special Interest Group'
|
||||
copyright = u'%s, OpenStack API Special Interest Group Team' % datetime.date.today().year
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
|
@ -191,8 +191,8 @@ latex_elements = {
|
|||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'api-wg.tex', u'API Working Group',
|
||||
u'OpenStack API Working Group Team', 'manual'),
|
||||
('index', 'api-sig.tex', u'API Special Interest Group',
|
||||
u'OpenStack API Special Interest Group Team', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
|
@ -221,8 +221,8 @@ latex_documents = [
|
|||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
('index', 'api-wg', u'API Working Group',
|
||||
u'OpenStack API Working Group Team', 'nova-specs', 'Guidelines for OpenStack APIs.',
|
||||
('index', 'api-sig', u'API Special Interest Group',
|
||||
u'OpenStack API Special Interest Group Team', 'nova-specs', 'Guidelines for OpenStack APIs.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
@ -239,10 +239,10 @@ texinfo_documents = [
|
|||
# -- Options for Epub output ---------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = u'API Working Group'
|
||||
epub_author = u'OpenStack API Working Group Team'
|
||||
epub_publisher = u'OpenStack API Working Group Team'
|
||||
epub_copyright = u'2014, OpenStack API Working Group Team'
|
||||
epub_title = u'API Special Interest Group'
|
||||
epub_author = u'OpenStack API Special Interest Group Team'
|
||||
epub_publisher = u'OpenStack API Special Interest Group Team'
|
||||
epub_copyright = u'2014, OpenStack API Special Interest Group Team'
|
||||
|
||||
# The language of the text. It defaults to the language option
|
||||
# or en if the language is not set.
|
||||
|
|
|
@ -2,17 +2,17 @@
|
|||
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.
|
||||
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 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?").
|
||||
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
|
||||
---------------------------
|
||||
|
@ -46,35 +46,34 @@ group for a live review of your project:
|
|||
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.
|
||||
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
|
||||
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.
|
||||
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 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.
|
||||
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 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
|
||||
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.
|
||||
|
||||
|
|
|
@ -1,8 +1,8 @@
|
|||
.. api-wg documentation master file
|
||||
|
||||
===========================
|
||||
OpenStack API Working Group
|
||||
===========================
|
||||
====================================
|
||||
OpenStack API Special Interest Group
|
||||
====================================
|
||||
|
||||
Mission Statement
|
||||
-----------------
|
||||
|
@ -19,8 +19,8 @@ This document contains the guidelines and rules for OpenStack project
|
|||
APIs including guidelines and proposed rules concerning API consistency, naming
|
||||
conventions, and best practice recommendations.
|
||||
|
||||
If you would like to connect with the API Working Group, visit the wiki at:
|
||||
https://wiki.openstack.org/wiki/API_Working_Group
|
||||
If you would like to connect with the API Special Interest Group, visit the
|
||||
wiki at: https://wiki.openstack.org/wiki/API_Working_Group
|
||||
|
||||
If you are interested in contributing to this document, the git repository is
|
||||
available at: http://git.openstack.org/cgit/openstack/api-wg/
|
||||
|
@ -30,13 +30,13 @@ http://docs.openstack.org/infra/manual/developers.html
|
|||
|
||||
|
||||
.. warning::
|
||||
These documents from the API Working Group are primarily focused on
|
||||
providing advice and guidelines for JSON-based APIs. While other
|
||||
These documents from the API Special Interest Group are primarily focused
|
||||
on providing advice and guidelines for JSON-based APIs. While other
|
||||
representations have their place in the OpenStack ecosystem, they present
|
||||
such a diversity of challenges and edge cases, especially with large
|
||||
and/or binary request and response bodies, that it is impossible to
|
||||
provide guidance that is complete. Where there is doubt refer to the
|
||||
HTTP RFCs, 7230 through 7235, as the ultimate authority.
|
||||
such a diversity of challenges and edge cases, especially with large and/or
|
||||
binary request and response bodies, that it is impossible to provide
|
||||
guidance that is complete. Where there is doubt refer to the HTTP RFCs,
|
||||
7230 through 7235, as the ultimate authority.
|
||||
|
||||
Guidelines
|
||||
----------
|
||||
|
|
|
@ -4,22 +4,22 @@ Cross-Project Liaisons
|
|||
Description
|
||||
-----------
|
||||
|
||||
The API Working Group seeks API subject matter experts for each project to
|
||||
communicate plans for API updates, review API guidelines with their project's
|
||||
view in mind, and review the API Working Group guidelines as they are drafted.
|
||||
The Cross-Project Liaison (CPL) should be familiar with the project's REST API
|
||||
design and future planning for changes to it.
|
||||
The API Special Interest Group seeks API subject matter experts for each
|
||||
project to communicate plans for API updates, review API guidelines with their
|
||||
project's view in mind, and review the API Special Interest Group guidelines as
|
||||
they are drafted. The Cross-Project Liaison (CPL) should be familiar with the
|
||||
project's REST API design and future planning for changes to it.
|
||||
|
||||
* The liaison should be the PTL or whomever they delegate to be their
|
||||
representative
|
||||
* The liaison is the first line of contact for the API Working Group team
|
||||
members
|
||||
* The liaison is the first line of contact for the API Special Interest Group
|
||||
team members
|
||||
* The liaison may further delegate work to other subject matter experts
|
||||
* The liaison should be aware of and engaged in the API Working Group
|
||||
* The liaison should be aware of and engaged in the API Special Interest Group
|
||||
`Communication channels
|
||||
<https://wiki.openstack.org/wiki/API_Working_Group#Communication>`_
|
||||
* The Nova team has been very explicit about how they will liaise with the
|
||||
API Working Group, see the `Responsibilities of Liaisons <https://wiki.openstack.org/wiki/Nova/APIWGLiaisons>`_
|
||||
API Special Interest Group; see the `Responsibilities of Liaisons <https://wiki.openstack.org/wiki/Nova/APIWGLiaisons>`_
|
||||
|
||||
Tooling
|
||||
-------
|
||||
|
|
|
@ -7,107 +7,101 @@ trivial changeset in the guidelines directory. A non trivial changeset
|
|||
is one which is more than a spelling/grammar typo or reformatting
|
||||
change.
|
||||
|
||||
The guidelines are initially intended to be a working group draft
|
||||
document. Our intent is to move fairly quickly to get published draft
|
||||
guidelines so this process reflects a preference for efficiency while
|
||||
gathering consensus.
|
||||
The guidelines are initially intended to be a group draft document. Our intent
|
||||
is to move fairly quickly to get published draft guidelines so this process
|
||||
reflects a preference for efficiency while gathering consensus.
|
||||
|
||||
Review process
|
||||
--------------
|
||||
|
||||
For trivial changes (as defined above) there is no minimum time that
|
||||
they must be proposed before merging. They must have at least one +1
|
||||
vote other than the approver and no -1. Once this is true a working
|
||||
group core may merge the change.
|
||||
For trivial changes (as defined above) there is no minimum time that they must
|
||||
be proposed before merging. They must have at least one +1 vote other than the
|
||||
approver and no -1. Once this is true a working group core may merge the
|
||||
change.
|
||||
|
||||
For changes which add a new guideline or make substantial changes to
|
||||
an existing guideline reaching consensus is an explicit goal. To
|
||||
that end there is a well defined process to ensure that proposals
|
||||
receive adequate review by the working group, cross project
|
||||
liaisons, and the OpenStack community at large.
|
||||
For changes which add a new guideline or make substantial changes to an
|
||||
existing guideline reaching consensus is an explicit goal. To that end there is
|
||||
a well defined process to ensure that proposals receive adequate review by the
|
||||
API Special Interest Group, cross project liaisons, and the OpenStack community
|
||||
at large.
|
||||
|
||||
In the various stages of the review process (defined below) consensus
|
||||
means the changeset is in its near final form for at least two working
|
||||
days. Minor typo/formatting changes do not reset the counter. There
|
||||
must be at least four +1 votes and no -1 votes unless the concern
|
||||
related to the -1 vote has been discussed in an API WG meeting. Once
|
||||
the matter has been discussed there should be no more than 20% of
|
||||
votes cast as -1 votes.
|
||||
In the various stages of the review process (defined below) consensus means the
|
||||
changeset is in its near final form for at least two working days. Minor
|
||||
typo/formatting changes do not reset the counter. There must be at least four
|
||||
+1 votes and no -1 votes unless the concern related to the -1 vote has been
|
||||
discussed in an API WG meeting. Once the matter has been discussed there should
|
||||
be no more than 20% of votes cast as -1 votes.
|
||||
|
||||
Discussion on Gerrit should be encouraged as the primary response.
|
||||
When discussion on IRC (in meetings or otherwise) is required that
|
||||
discussion should be summarized back to Gerrit.
|
||||
Discussion on Gerrit should be encouraged as the primary response. When
|
||||
discussion on IRC (in meetings or otherwise) is required that discussion should
|
||||
be summarized back to Gerrit.
|
||||
|
||||
That process is:
|
||||
|
||||
1. Working group members should review proposed guideline changes
|
||||
1. API Special Interest Group members should review proposed guideline changes
|
||||
and reach consensus.
|
||||
|
||||
2. When consensus is reached within the group the guideline should
|
||||
be marked as *frozen* and cross project liaisons (CPLs) should
|
||||
be invited to review the guideline. There is an ``add-reviewers.py``
|
||||
script to do this. See :doc:`liaisons` for more information.
|
||||
2. When consensus is reached within the group the guideline should be marked as
|
||||
*frozen* and cross project liaisons (CPLs) should be invited to review the
|
||||
guideline. There is an ``add-reviewers.py`` script to do this. See
|
||||
:doc:`liaisons` for more information.
|
||||
|
||||
A proposal can be frozen by exactly one core reviewer by setting
|
||||
Code-Review +2. Only the core reviewer responsible for freezing the
|
||||
proposal should +2 it. All other core reviewers should vote with at
|
||||
most a +1 when reviewing.
|
||||
A proposal can be frozen by exactly one core reviewer by setting Code-Review
|
||||
+2. Only the core reviewer responsible for freezing the proposal should +2
|
||||
it. All other core reviewers should vote with at most a +1 when reviewing.
|
||||
|
||||
3. The CPLs have one week to review the proposal. If there are no
|
||||
reviews lazy consensus is assumed. If there is a -1 review by a CPL
|
||||
that requires an update to the changeset, it does not reset the 1
|
||||
week the CPLs have to review it.
|
||||
3. The CPLs have one week to review the proposal. If there are no reviews lazy
|
||||
consensus is assumed. If there is a -1 review by a CPL that requires an
|
||||
update to the changeset, it does not reset the 1 week the CPLs have to
|
||||
review it.
|
||||
|
||||
4. When there is consensus from the CPLs, the proposal may be
|
||||
merged.
|
||||
4. When there is consensus from the CPLs, the proposal may be merged.
|
||||
|
||||
To avoid opportunities for miscommunication, the core working
|
||||
group member who froze the changeset should be responsible for
|
||||
merging it. If that core is unavailable for enough time to cause
|
||||
a delay then the responsibility falls to one of the others cores.
|
||||
To avoid opportunities for miscommunication, the core working group member
|
||||
who froze the changeset should be responsible for merging it. If that core
|
||||
is unavailable for enough time to cause a delay then the responsibility
|
||||
falls to one of the others cores.
|
||||
|
||||
An email should be sent to the openstack-dev mailing list containing
|
||||
the links to all of the guidelines that have recently merged. The
|
||||
finalized guidelines should be buffered such that a maximum of one
|
||||
announcement email is sent per week.
|
||||
An email should be sent to the openstack-dev mailing list containing the
|
||||
links to all of the guidelines that have recently merged. The finalized
|
||||
guidelines should be buffered such that a maximum of one announcement email
|
||||
is sent per week.
|
||||
|
||||
If at any time during this process there is difficulty reaching
|
||||
consensus or an apparent lack of information or input, additional
|
||||
input should be sought from the rest of the community. Two ways to
|
||||
do this include (preferring email):
|
||||
If at any time during this process there is difficulty reaching consensus or an
|
||||
apparent lack of information or input, additional input should be sought from
|
||||
the rest of the community. Two ways to do this include (preferring email):
|
||||
|
||||
1. The openstack-dev mailing list. An email may be sent to the
|
||||
openstack-dev mailing list with the subject "[all][api] New API
|
||||
Guidelines Ready for Cross Project Review". The email should contain
|
||||
links to the guidelines that need additional input.
|
||||
1. The openstack-dev mailing list. An email may be sent to the openstack-dev
|
||||
mailing list with the subject "[all][api] New API Guidelines Ready for Cross
|
||||
Project Review". The email should contain links to the guidelines that need
|
||||
additional input.
|
||||
|
||||
2. The `Cross Project Meeting
|
||||
<https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting>`_. An
|
||||
agenda item should be added to the Cross Project Meeting which
|
||||
indicates need for discussion. Links to the guidelines that need
|
||||
additional input should be provided. When this is done an API WG
|
||||
member must attend the meeting to highlight the agenda item.
|
||||
<https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting>`_. An agenda
|
||||
item should be added to the Cross Project Meeting which indicates need for
|
||||
discussion. Links to the guidelines that need additional input should be
|
||||
provided. When this is done an API WG member must attend the meeting to
|
||||
highlight the agenda item.
|
||||
|
||||
Merged guidelines comprise a draft of the official guidelines. Before
|
||||
an official version of the guidelines can be released the following
|
||||
has to occur:
|
||||
Merged guidelines comprise a draft of the official guidelines. Before an
|
||||
official version of the guidelines can be released the following has to occur:
|
||||
|
||||
* An 80% (of votes cast) majority vote on the document as a whole
|
||||
with one vote per OpenStack PTL (or delegate).
|
||||
* An 80% (of votes cast) majority vote on the document as a whole with one vote
|
||||
per OpenStack PTL (or delegate).
|
||||
|
||||
* Reviewed and approved by the TC. The API WG is a delegated group from
|
||||
the TC so the TC ultimately get final say on what the working
|
||||
group are able to release.
|
||||
* Reviewed and approved by the TC. The API WG is a delegated group from the TC
|
||||
so the TC ultimately get final say on what the working group are able to
|
||||
release.
|
||||
|
||||
Proposing a new guideline
|
||||
-------------------------
|
||||
|
||||
When proposing a new guideline you should start by using the
|
||||
:doc:`guideline template <template>` to generate the basic
|
||||
structure. Copy the ``template.rst`` file to the ``guidelines`` directory
|
||||
with a filename reflecting your new guideline (for example
|
||||
``guidelines/errors.rst``), and then follow the instructions within the
|
||||
template. Once complete you should follow the `developer workflow`_ and
|
||||
the previously stated review process to have your guideline accepted.
|
||||
When proposing a new guideline you should start by using the :doc:`guideline
|
||||
template <template>` to generate the basic structure. Copy the ``template.rst``
|
||||
file to the ``guidelines`` directory with a filename reflecting your new
|
||||
guideline (for example ``guidelines/errors.rst``), and then follow the
|
||||
instructions within the template. Once complete you should follow the
|
||||
`developer workflow`_ and the previously stated review process to have your
|
||||
guideline accepted.
|
||||
|
||||
.. _developer workflow: http://docs.openstack.org/infra/manual/developers.html
|
||||
|
|
|
@ -47,7 +47,7 @@ introduction if applicable.
|
|||
Guidance
|
||||
********
|
||||
|
||||
The actual guidance that the API working group would like to provide.
|
||||
The actual guidance that the API Special Interest Group would like to provide.
|
||||
|
||||
* The guideline should provide a clear recitation of the actions to be
|
||||
taken by implementors.
|
||||
|
|
|
@ -67,11 +67,11 @@ makes:
|
|||
* Change in APIs is an inevitable consequence of evolving projects with a
|
||||
diversity of contributors. In the unlikely event that such change is not
|
||||
a consideration then these guidelines need not apply.
|
||||
* The overarching goal of the API Working Group is to encourage consistency
|
||||
in the APIs of all the services. The proposed solutions for enabling
|
||||
compatibility and stability are guidance towards achieving consistency.
|
||||
The assertions about when a change will violate interoperability are true
|
||||
independent of any given solution.
|
||||
* The overarching goal of the API Special Interest Group is to encourage
|
||||
consistency in the APIs of all the services. The proposed solutions for
|
||||
enabling compatibility and stability are guidance towards achieving
|
||||
consistency. The assertions about when a change will violate
|
||||
interoperability are true independent of any given solution.
|
||||
|
||||
Any service which does not support versioning and wishes to achieve
|
||||
interoperability SHOULD do two things:
|
||||
|
@ -86,7 +86,7 @@ interoperability SHOULD do two things:
|
|||
adhering to these guidelines for interoperability. The project itself
|
||||
must make the decisions on how to evolve their API. If this leads to
|
||||
conflicts with other projects within the OpenStack ecosystem, the
|
||||
role of the API-WG is solely to help clarify the guidelines and
|
||||
role of the API-SIG is solely to help clarify the guidelines and
|
||||
provide advice on how to minimize the impact of changes. The
|
||||
Technical Committee is the body which provides adjudication and
|
||||
mediation when consensus cannot be reached.
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
[metadata]
|
||||
name = api-wg
|
||||
summary = OpenStack API Workgroup Guidelines
|
||||
name = api-sig
|
||||
summary = OpenStack API Special Interest Group Guidelines
|
||||
description-file =
|
||||
README.rst
|
||||
author = OpenStack
|
||||
|
|
|
@ -11,11 +11,11 @@ logger = logging.getLogger(__name__)
|
|||
def parse_args():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Add the cross-project liaisons as reviewers " \
|
||||
"on an API working group review.")
|
||||
"on an API Special Interest Group review.")
|
||||
parser.add_argument('--debug', help="Print debugging information",
|
||||
action='store_true')
|
||||
parser.add_argument("username", help="Your Gerrit username", type=str)
|
||||
parser.add_argument("review", help="An API WG Gerrit review", type=str)
|
||||
parser.add_argument("review", help="An API-SIG Gerrit review", type=str)
|
||||
args = parser.parse_args()
|
||||
|
||||
return (args.debug, args.username, args.review)
|
||||
|
|
Loading…
Reference in New Issue