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

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,
+This repository contains documents from the OpenStack API Special Interest
-including guidelines and proposed rules concerning API consistency, naming
+Group, including guidelines and proposed rules concerning API consistency,
-conventions, and best practice recommendations. The published
+naming conventions, and best practice recommendations. The published
 information can be found at `specs.openstack.org
 <http://specs.openstack.org/openstack/api-wg/>`_.
 

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'
+project = u'API Special Interest Group'
-copyright = u'%s, OpenStack API Working Group Team' % datetime.date.today().year
+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',
+  ('index', 'api-sig.tex', u'API Special Interest Group',
-   u'OpenStack API Working Group Team', 'manual'),
+   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',
+  ('index', 'api-sig', u'API Special Interest Group',
-   u'OpenStack API Working Group Team', 'nova-specs', 'Guidelines for OpenStack APIs.',
+   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_title = u'API Special Interest Group'
-epub_author = u'OpenStack API Working Group Team'
+epub_author = u'OpenStack API Special Interest Group Team'
-epub_publisher = u'OpenStack API Working Group Team'
+epub_publisher = u'OpenStack API Special Interest Group Team'
-epub_copyright = u'2014, OpenStack API Working 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.

doc/source/guidedreview.rst

@@ -2,17 +2,17 @@
 Guided Review Process
 =====================
 
-The API working group would like to increase the tools available to OpenStack
+The API Special Interest Group would like to increase the tools available to
-project teams by defining a process and venue for conducting live face-to-face
+OpenStack project teams by defining a process and venue for conducting live
-reviews. At a high level, these reviews are focused on the question "does my
+face-to-face reviews. At a high level, these reviews are focused on the
-project align with the guidelines?" and are intended to be hosted by the
+question "does my project align with the guidelines?" and are intended to be
-working group at the PTG meetups.
+hosted by the API Special Interest Group at the PTG meetups.
 
-On a more concrete level, the working group expects that reviews which are
+On a more concrete level, the API Special Interest Group expects that reviews
-directed towards specific areas, or problems within, an API will garner the
+which are directed towards specific areas, or problems within, an API will
-best results (e.g. "Is using a PUT request for updating these resources
+garner the best results (e.g. "Is using a PUT request for updating these
-appropriate?", "We are using GET requests to start server actions, is there a
+resources appropriate?", "We are using GET requests to start server actions, is
-better alternative?").
+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
+Then just show up to an API Special Interest Group face-to-face session with
-materials ready. Sending an email ahead of time will help to ensure that the
+your materials ready. Sending an email ahead of time will help to ensure that
-group is ready for your review but is not strictly necessary.
+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
+group. You should expect to have clarification on the basic question of how
-question of how close your API follows the working group's guidelines. But,
+close your API follows the API-SIG's guidelines. But, the depth of your review
-the depth of your review will depend entirely on how big a request is made of
+will depend entirely on how big a request is made of the review group.
-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
+When considering approaching the API-SIG for a review, we encourage projects to
-projects to identify areas of their APIs that could use clarification or have
+identify areas of their APIs that could use clarification or have been
-been problematic to the team. Project teams that have reviewed the API
+problematic to the team. Project teams that have reviewed the API guidelines
-guidelines and have questions about specific areas of interest will find that
+and have questions about specific areas of interest will find that their
-their reviews will be more productive than open-ended questions which cover
+reviews will be more productive than open-ended questions which cover large
-large portions of their API.
+portions of their API.
 
-After a review is completed, the API working group will archive the general
+After a review is completed, the API Special Interest Group will archive the
-details of the review (e.g. "Team <X> requested a review of API features <Y>
+general details of the review (e.g. "Team <X> requested a review of API
-and <Z>. It was agreed that actions <A>, <B> and <C> are the best path
+features <Y> and <Z>. It was agreed that actions <A>, <B> and <C> are the best
-forward") and any artifacts that are generated during the process. This
+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.
 

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:
+If you would like to connect with the API Special Interest Group, visit the
-https://wiki.openstack.org/wiki/API_Working_Group
+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
+    These documents from the API Special Interest Group are primarily focused
-    providing advice and guidelines for JSON-based APIs. While other
+    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
+    such a diversity of challenges and edge cases, especially with large and/or
-    and/or binary request and response bodies, that it is impossible to
+    binary request and response bodies, that it is impossible to provide
-    provide guidance that is complete. Where there is doubt refer to the
+    guidance that is complete. Where there is doubt refer to the HTTP RFCs,
-    HTTP RFCs, 7230 through 7235, as the ultimate authority.
+    7230 through 7235, as the ultimate authority.
 
 Guidelines
 ----------

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
+The API Special Interest Group seeks API subject matter experts for each
-communicate plans for API updates, review API guidelines with their project's
+project to communicate plans for API updates, review API guidelines with their
-view in mind, and review the API Working Group guidelines as they are drafted.
+project's view in mind, and review the API Special Interest Group guidelines as
-The Cross-Project Liaison (CPL) should be familiar with the project's REST API
+they are drafted.  The Cross-Project Liaison (CPL) should be familiar with the
-design and future planning for changes to it.
+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
+* The liaison is the first line of contact for the API Special Interest Group
-  members
+  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
 -------

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
+The guidelines are initially intended to be a group draft document. Our intent
-document. Our intent is to move fairly quickly to get published draft
+is to move fairly quickly to get published draft guidelines so this process
-guidelines so this process reflects a preference for efficiency while
+reflects a preference for efficiency while gathering consensus.
-gathering consensus.
 
 Review process
 --------------
 
-For trivial changes (as defined above) there is no minimum time that
+For trivial changes (as defined above) there is no minimum time that they must
-they must be proposed before merging. They must have at least one +1
+be proposed before merging. They must have at least one +1 vote other than the
-vote other than the approver and no -1. Once this is true a working
+approver and no -1. Once this is true a working group core may merge the
-group core may merge the change.
+change.
 
-For changes which add a new guideline or make substantial changes to
+For changes which add a new guideline or make substantial changes to an
-an existing guideline reaching consensus is an explicit goal. To
+existing guideline reaching consensus is an explicit goal. To that end there is
-that end there is a well defined process to ensure that proposals
+a well defined process to ensure that proposals receive adequate review by the
-receive adequate review by the working group, cross project
+API Special Interest Group, cross project liaisons, and the OpenStack community
-liaisons, and the OpenStack community at large.
+at large.
 
-In the various stages of the review process (defined below) consensus
+In the various stages of the review process (defined below) consensus means the
-means the changeset is in its near final form for at least two working
+changeset is in its near final form for at least two working days. Minor
-days. Minor typo/formatting changes do not reset the counter. There
+typo/formatting changes do not reset the counter. There must be at least four
-must be at least four +1 votes and no -1 votes unless the concern
++1 votes and no -1 votes unless the concern related to the -1 vote has been
-related to the -1 vote has been discussed in an API WG meeting. Once
+discussed in an API WG meeting. Once the matter has been discussed there should
-the matter has been discussed there should be no more than 20% of
+be no more than 20% of votes cast as -1 votes.
-votes cast as -1 votes.
 
-Discussion on Gerrit should be encouraged as the primary response.
+Discussion on Gerrit should be encouraged as the primary response.  When
-When discussion on IRC (in meetings or otherwise) is required that
+discussion on IRC (in meetings or otherwise) is required that discussion should
-discussion should be summarized back to Gerrit.
+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
+2. When consensus is reached within the group the guideline should be marked as
-   be marked as *frozen* and cross project liaisons (CPLs) should
+   *frozen* and cross project liaisons (CPLs) should be invited to review the
-   be invited to review the guideline. There is an ``add-reviewers.py``
+   guideline. There is an ``add-reviewers.py`` script to do this. See
-   script to do this. See :doc:`liaisons` for more information.
+   :doc:`liaisons` for more information.
 
-   A proposal can be frozen by exactly one core reviewer by setting
+   A proposal can be frozen by exactly one core reviewer by setting Code-Review
-   Code-Review +2. Only the core reviewer responsible for freezing the
+   +2. Only the core reviewer responsible for freezing the proposal should +2
-   proposal should +2 it. All other core reviewers should vote with at
+   it. All other core reviewers should vote with at most a +1 when reviewing.
-   most a +1 when reviewing.
 
-3. The CPLs have one week to review the proposal. If there are no
+3. The CPLs have one week to review the proposal. If there are no reviews lazy
-   reviews lazy consensus is assumed. If there is a -1 review by a CPL
+   consensus is assumed. If there is a -1 review by a CPL that requires an
-   that requires an update to the changeset, it does not reset the 1
+   update to the changeset, it does not reset the 1 week the CPLs have to
-   week the CPLs have to review it.
+   review it.
 
-4. When there is consensus from the CPLs, the proposal may be
+4. When there is consensus from the CPLs, the proposal may be merged.
-   merged.
 
-   To avoid opportunities for miscommunication, the core working
+   To avoid opportunities for miscommunication, the core working group member
-   group member who froze the changeset should be responsible for
+   who froze the changeset should be responsible for merging it. If that core
-   merging it. If that core is unavailable for enough time to cause
+   is unavailable for enough time to cause a delay then the responsibility
-   a delay then the responsibility falls to one of the others cores.
+   falls to one of the others cores.
 
-   An email should be sent to the openstack-dev mailing list containing
+   An email should be sent to the openstack-dev mailing list containing the
-   the links to all of the guidelines that have recently merged. The
+   links to all of the guidelines that have recently merged. The finalized
-   finalized guidelines should be buffered such that a maximum of one
+   guidelines should be buffered such that a maximum of one announcement email
-   announcement email is sent per week.
+   is sent per week.
 
-If at any time during this process there is difficulty reaching
+If at any time during this process there is difficulty reaching consensus or an
-consensus or an apparent lack of information or input, additional
+apparent lack of information or input, additional input should be sought from
-input should be sought from the rest of the community. Two ways to
+the rest of the community. Two ways to do this include (preferring email):
-do this include (preferring email):
 
-1. The openstack-dev mailing list. An email may be sent to the
+1. The openstack-dev mailing list. An email may be sent to the openstack-dev
-   openstack-dev mailing list with the subject "[all][api] New API
+   mailing list with the subject "[all][api] New API Guidelines Ready for Cross
-   Guidelines Ready for Cross Project Review". The email should contain
+   Project Review". The email should contain links to the guidelines that need
-   links to the guidelines that need additional input.
+   additional input.
 
 2. The `Cross Project Meeting
-   <https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting>`_. An
+   <https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting>`_. An agenda
-   agenda item should be added to the Cross Project Meeting which
+   item should be added to the Cross Project Meeting which indicates need for
-   indicates need for discussion. Links to the guidelines that need
+   discussion. Links to the guidelines that need additional input should be
-   additional input should be provided. When this is done an API WG
+   provided. When this is done an API WG member must attend the meeting to
-   member must attend the meeting to highlight the agenda item.
+   highlight the agenda item.
 
-Merged guidelines comprise a draft of the official guidelines. Before
+Merged guidelines comprise a draft of the official guidelines. Before an
-an official version of the guidelines can be released the following
+official version of the guidelines can be released the following has to occur:
-has to occur:
 
-* An 80% (of votes cast) majority vote on the document as a whole
+* An 80% (of votes cast) majority vote on the document as a whole with one vote
-  with one vote per OpenStack PTL (or delegate).
+  per OpenStack PTL (or delegate).
 
-* Reviewed and approved by the TC. The API WG is a delegated group from
+* Reviewed and approved by the TC. The API WG is a delegated group from the TC
-  the TC so the TC ultimately get final say on what the working
+  so the TC ultimately get final say on what the working group are able to
-  group are able to release.
+  release.
 
 Proposing a new guideline
 -------------------------
 
-When proposing a new guideline you should start by using the
+When proposing a new guideline you should start by using the :doc:`guideline
-:doc:`guideline template <template>` to generate the basic
+template <template>` to generate the basic structure. Copy the ``template.rst``
-structure. Copy the ``template.rst`` file to the ``guidelines`` directory
+file to the ``guidelines`` directory with a filename reflecting your new
-with a filename reflecting your new guideline (for example
+guideline (for example ``guidelines/errors.rst``), and then follow the
-``guidelines/errors.rst``), and then follow the instructions within the
+instructions within the template. Once complete you should follow the
-template. Once complete you should follow the `developer workflow`_ and
+`developer workflow`_ and the previously stated review process to have your
-the previously stated review process to have your guideline accepted.
+guideline accepted.
 
 .. _developer workflow: http://docs.openstack.org/infra/manual/developers.html

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.

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
+* The overarching goal of the API Special Interest Group is to encourage
-  in the APIs of all the services. The proposed solutions for enabling
+  consistency in the APIs of all the services. The proposed solutions for
-  compatibility and stability are guidance towards achieving consistency.
+  enabling compatibility and stability are guidance towards achieving
-  The assertions about when a change will violate interoperability are true
+  consistency.  The assertions about when a change will violate
-  independent of any given solution.
+  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.

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
-name = api-wg
+name = api-sig
-summary = OpenStack API Workgroup Guidelines
+summary = OpenStack API Special Interest Group Guidelines
 description-file =
     README.rst
 author = OpenStack

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)