Browse Source

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
changes/42/508242/2
Ed Leafe 5 years ago
parent
commit
9fd03c71c7
  1. 10
      README.rst
  2. 22
      doc/source/conf.py
  3. 57
      doc/source/guidedreview.rst
  4. 22
      doc/source/index.rst
  5. 18
      doc/source/liaisons.rst
  6. 148
      doc/source/process.rst
  7. 2
      doc/source/template.rst
  8. 12
      guidelines/api_interoperability.rst
  9. 4
      setup.cfg
  10. 4
      tools/add-reviewers.py

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/>`_.

22
doc/source/conf.py

@ -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.

57
doc/source/guidedreview.rst

@ -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.
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?").
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
---------------------------
@ -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.
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
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.

22
doc/source/index.rst

@ -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
----------

18
doc/source/liaisons.rst

@ -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
-------

148
doc/source/process.rst

@ -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 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.
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.
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
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.
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

2
doc/source/template.rst

@ -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.

12
guidelines/api_interoperability.rst

@ -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.

4
setup.cfg

@ -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

4
tools/add-reviewers.py

@ -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…
Cancel
Save