From 9fd03c71c7db01a1bf9d56bfe0506a029d6542fe Mon Sep 17 00:00:00 2001 From: Ed Leafe Date: Thu, 28 Sep 2017 17:04:15 +0000 Subject: [PATCH] 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 | 10 +- doc/source/conf.py | 22 ++--- doc/source/guidedreview.rst | 53 +++++------ doc/source/index.rst | 22 ++--- doc/source/liaisons.rst | 18 ++-- doc/source/process.rst | 142 +++++++++++++--------------- doc/source/template.rst | 2 +- guidelines/api_interoperability.rst | 12 +-- setup.cfg | 4 +- tools/add-reviewers.py | 4 +- 10 files changed, 141 insertions(+), 148 deletions(-) diff --git a/README.rst b/README.rst index 4a02bce..7762c6a 100644 --- a/README.rst +++ b/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 `_. diff --git a/doc/source/conf.py b/doc/source/conf.py index 8ff1e56..8da32a7 100644 --- a/doc/source/conf.py +++ b/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. diff --git a/doc/source/guidedreview.rst b/doc/source/guidedreview.rst index 3411ede..6dccf5e 100644 --- a/doc/source/guidedreview.rst +++ b/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. +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 requested a review of API features -and . It was agreed that actions , and 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 requested a review of API +features and . It was agreed that actions , and 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 6d62c83..49d3ea8 100644 --- a/doc/source/index.rst +++ b/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 ---------- diff --git a/doc/source/liaisons.rst b/doc/source/liaisons.rst index 829e9cf..3f8d1fc 100644 --- a/doc/source/liaisons.rst +++ b/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 `_ * The Nova team has been very explicit about how they will liaise with the - API Working Group, see the `Responsibilities of Liaisons `_ + API Special Interest Group; see the `Responsibilities of Liaisons `_ Tooling ------- diff --git a/doc/source/process.rst b/doc/source/process.rst index d5b63be..fc877cd 100644 --- a/doc/source/process.rst +++ b/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 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 - `_. 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. + `_. 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