├── .gitignore ├── .gitreview ├── .stestr.conf ├── .zuul.yaml ├── LICENSE ├── README.rst ├── doc └── source │ ├── conf.py │ ├── guidedreview.rst │ ├── guidelines │ ├── index.rst │ ├── liaisons.json │ ├── liaisons.rst │ ├── process.rst │ └── template.rst ├── guidelines ├── api-docs.rst ├── api_interoperability.rst ├── compatibility.rst ├── consuming-catalog.rst ├── consuming-catalog │ ├── authority.rst │ ├── endpoint.rst │ └── version-discovery.rst ├── counting.rst ├── discoverability.rst ├── dns-sd.rst ├── errors-example.json ├── errors-schema.json ├── errors.rst ├── etags.rst ├── evaluating_api_changes.rst ├── extensions.rst ├── general.rst ├── headers.rst ├── http.rst ├── http │ ├── caching.rst │ ├── methods.rst │ └── response-codes.rst ├── links.rst ├── metadata.rst ├── microversion-errors-example.json ├── microversion_specification.rst ├── naming.rst ├── pagination_filter_sort.rst ├── representation_structure.rst ├── sdk-exposing-microversions.rst ├── tags.rst ├── terms.rst ├── testing.rst ├── time.rst ├── uri.rst ├── version-discovery-schema.json ├── version-information-schema.json └── versioned-discovery-schema.json ├── requirements.txt ├── setup.cfg ├── setup.py ├── tests ├── __init__.py └── test_titles.py ├── tools └── add-reviewers.py └── tox.ini /.gitignore: -------------------------------------------------------------------------------- 1 | AUTHORS 2 | ChangeLog 3 | build 4 | .tox 5 | .venv 6 | *.egg* 7 | *.swp 8 | *.swo 9 | *.pyc 10 | .stestr/ 11 | -------------------------------------------------------------------------------- /.gitreview: -------------------------------------------------------------------------------- 1 | [gerrit] 2 | host=review.opendev.org 3 | port=29418 4 | project=openstack/api-sig.git 5 | -------------------------------------------------------------------------------- /.stestr.conf: -------------------------------------------------------------------------------- 1 | [DEFAULT] 2 | test_path=./tests 3 | top_dir=./ 4 | 5 | -------------------------------------------------------------------------------- /.zuul.yaml: -------------------------------------------------------------------------------- 1 | - project: 2 | templates: 3 | - openstack-specs-jobs 4 | check: 5 | jobs: 6 | - openstack-tox-py37 7 | - openstack-tox-linters 8 | gate: 9 | jobs: 10 | - openstack-tox-py37 11 | - openstack-tox-linters 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | This work is licensed under a Creative Commons Attribution 3.0 Unported License. 2 | 3 | http://creativecommons.org/licenses/by/3.0/legalcode 4 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | ====== 2 | README 3 | ====== 4 | 5 | Openstack API Special Interest Group documents 6 | ---------------------------------------------- 7 | 8 | This repository contains documents from the OpenStack API Special Interest 9 | Group, including guidelines and proposed rules concerning API consistency, 10 | naming conventions, and best practice recommendations. The published 11 | information can be found at `specs.openstack.org 12 | `_. 13 | 14 | Interested in contributing to the API conversations? Simply clone this 15 | repository and follow the `OpenStack code and review submission 16 | processes `_ 17 | and the `process document 18 | `_. 19 | -------------------------------------------------------------------------------- /doc/source/conf.py: -------------------------------------------------------------------------------- 1 | # Tempest documentation build configuration file, created by 2 | # sphinx-quickstart on Tue May 21 17:43:32 2013. 3 | # 4 | # This file is execfile()d with the current directory set to its containing dir. 5 | # 6 | # Note that not all possible configuration values are present in this 7 | # autogenerated file. 8 | # 9 | # All configuration values have a default; values that are commented out 10 | # serve to show the default. 11 | 12 | import datetime 13 | import sys 14 | import os 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | sys.path.insert(0, os.path.abspath('.')) 20 | 21 | # -- General configuration ----------------------------------------------------- 22 | 23 | # If your documentation needs a minimal Sphinx version, state it here. 24 | #needs_sphinx = '1.0' 25 | 26 | # Add any Sphinx extension module names here, as strings. They can be extensions 27 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 28 | extensions = ['sphinx.ext.autodoc', 29 | 'sphinx.ext.todo', 30 | 'sphinx.ext.viewcode', 31 | 'openstackdocstheme', 32 | 'yasfb', 33 | ] 34 | 35 | # Feed configuration for yasfb 36 | feed_base_url = 'https://specs.openstack.org/openstack/api-sig' 37 | feed_author = 'OpenStack API Special Interest Group' 38 | 39 | todo_include_todos = True 40 | 41 | # Add any paths that contain templates here, relative to this directory. 42 | templates_path = ['_templates'] 43 | 44 | # The suffix of source filenames. 45 | source_suffix = '.rst' 46 | 47 | # The encoding of source files. 48 | #source_encoding = 'utf-8-sig' 49 | 50 | # The master toctree document. 51 | master_doc = 'index' 52 | 53 | # General information about the project. 54 | project = 'API Special Interest Group' 55 | copyright = '%s, OpenStack API Special Interest Group Team' % datetime.date.today().year 56 | 57 | # openstackdocstheme options 58 | openstackdocs_repo_name = 'openstack/api-sig' 59 | openstackdocs_auto_name = False 60 | 61 | # The language for content autogenerated by Sphinx. Refer to documentation 62 | # for a list of supported languages. 63 | #language = None 64 | 65 | # There are two options for replacing |today|: either, you set today to some 66 | # non-false value, then it is used: 67 | #today = '' 68 | # Else, today_fmt is used as the format for a strftime call. 69 | #today_fmt = '%B %d, %Y' 70 | 71 | # List of patterns, relative to source directory, that match files and 72 | # directories to ignore when looking for source files. 73 | exclude_patterns = [ 74 | '_build', 75 | ] 76 | 77 | # The reST default role (used for this markup: `text`) to use for all documents. 78 | #default_role = None 79 | 80 | # If true, '()' will be appended to :func: etc. cross-reference text. 81 | #add_function_parentheses = True 82 | 83 | # If true, the current module name will be prepended to all description 84 | # unit titles (such as .. function::). 85 | add_module_names = False 86 | 87 | # If true, sectionauthor and moduleauthor directives will be shown in the 88 | # output. They are ignored by default. 89 | show_authors = False 90 | 91 | # The name of the Pygments (syntax highlighting) style to use. 92 | pygments_style = 'native' 93 | 94 | # A list of ignored prefixes for module index sorting. 95 | modindex_common_prefix = [] 96 | 97 | # -- Options for man page output ---------------------------------------------- 98 | man_pages = [] 99 | 100 | # -- Options for HTML output --------------------------------------------------- 101 | 102 | # The theme to use for HTML and HTML Help pages. See the documentation for 103 | # a list of builtin themes. 104 | html_theme = 'openstackdocs' 105 | 106 | # Theme options are theme-specific and customize the look and feel of a theme 107 | # further. For a list of options available for each theme, see the 108 | # documentation. 109 | #html_theme_options = {} 110 | 111 | # Add any paths that contain custom themes here, relative to this directory. 112 | #html_theme_path = [] 113 | 114 | # The name for this set of Sphinx documents. If None, it defaults to 115 | # " v documentation". 116 | #html_title = None 117 | 118 | # A shorter title for the navigation bar. Default is the same as html_title. 119 | #html_short_title = None 120 | 121 | # The name of an image file (relative to this directory) to place at the top 122 | # of the sidebar. 123 | #html_logo = None 124 | 125 | # The name of an image file (within the static path) to use as favicon of the 126 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 127 | # pixels large. 128 | #html_favicon = None 129 | 130 | # If true, SmartyPants will be used to convert quotes and dashes to 131 | # typographically correct entities. 132 | #html_use_smartypants = True 133 | 134 | # Custom sidebar templates, maps document names to template names. 135 | #html_sidebars = {} 136 | 137 | # Additional templates that should be rendered to pages, maps page names to 138 | # template names. 139 | #html_additional_pages = {} 140 | 141 | # If false, no module index is generated. 142 | html_domain_indices = False 143 | 144 | # If false, no index is generated. 145 | html_use_index = False 146 | 147 | # If true, the index is split into individual pages for each letter. 148 | #html_split_index = False 149 | 150 | # If true, links to the reST sources are added to the pages. 151 | #html_show_sourcelink = True 152 | 153 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 154 | #html_show_sphinx = True 155 | 156 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 157 | #html_show_copyright = True 158 | 159 | # If true, an OpenSearch description file will be output, and all pages will 160 | # contain a tag referring to it. The value of this option must be the 161 | # base URL from which the finished HTML is served. 162 | #html_use_opensearch = '' 163 | 164 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 165 | #html_file_suffix = None 166 | 167 | # Output file base name for HTML help builder. 168 | htmlhelp_basename = 'API-Sig-Doc' 169 | 170 | 171 | # -- Options for LaTeX output -------------------------------------------------- 172 | 173 | latex_elements = { 174 | # The paper size ('letterpaper' or 'a4paper'). 175 | #'papersize': 'letterpaper', 176 | 177 | # The font size ('10pt', '11pt' or '12pt'). 178 | #'pointsize': '10pt', 179 | 180 | # Additional stuff for the LaTeX preamble. 181 | #'preamble': '', 182 | } 183 | 184 | # Grouping the document tree into LaTeX files. List of tuples 185 | # (source start file, target name, title, author, documentclass [howto/manual]). 186 | latex_documents = [ 187 | ('index', 'api-sig.tex', 'API Special Interest Group', 188 | 'OpenStack API Special Interest Group Team', 'manual'), 189 | ] 190 | 191 | # The name of an image file (relative to this directory) to place at the top of 192 | # the title page. 193 | #latex_logo = None 194 | 195 | # For "manual" documents, if this is true, then toplevel headings are parts, 196 | # not chapters. 197 | #latex_use_parts = False 198 | 199 | # If true, show page references after internal links. 200 | #latex_show_pagerefs = False 201 | 202 | # If true, show URL addresses after external links. 203 | #latex_show_urls = False 204 | 205 | # Documents to append as an appendix to all manuals. 206 | #latex_appendices = [] 207 | 208 | # If false, no module index is generated. 209 | #latex_domain_indices = True 210 | 211 | # -- Options for Texinfo output ------------------------------------------------ 212 | 213 | # Grouping the document tree into Texinfo files. List of tuples 214 | # (source start file, target name, title, author, 215 | # dir menu entry, description, category) 216 | texinfo_documents = [ 217 | ('index', 'api-sig', 'API Special Interest Group', 218 | 'OpenStack API Special Interest Group Team', 'nova-specs', 'Guidelines for OpenStack APIs.', 219 | 'Miscellaneous'), 220 | ] 221 | 222 | # Documents to append as an appendix to all manuals. 223 | #texinfo_appendices = [] 224 | 225 | # If false, no module index is generated. 226 | #texinfo_domain_indices = True 227 | 228 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 229 | #texinfo_show_urls = 'footnote' 230 | 231 | 232 | # -- Options for Epub output --------------------------------------------------- 233 | 234 | # Bibliographic Dublin Core info. 235 | epub_title = 'API Special Interest Group' 236 | epub_author = 'OpenStack API Special Interest Group Team' 237 | epub_publisher = 'OpenStack API Special Interest Group Team' 238 | epub_copyright = '2014, OpenStack API Special Interest Group Team' 239 | 240 | # The language of the text. It defaults to the language option 241 | # or en if the language is not set. 242 | #epub_language = '' 243 | 244 | # The scheme of the identifier. Typical schemes are ISBN or URL. 245 | #epub_scheme = '' 246 | 247 | # The unique identifier of the text. This can be a ISBN number 248 | # or the project homepage. 249 | #epub_identifier = '' 250 | 251 | # A unique identification for the text. 252 | #epub_uid = '' 253 | 254 | # A tuple containing the cover image and cover page html template filenames. 255 | #epub_cover = () 256 | 257 | # HTML files that should be inserted before the pages created by sphinx. 258 | # The format is a list of tuples containing the path and title. 259 | #epub_pre_files = [] 260 | 261 | # HTML files shat should be inserted after the pages created by sphinx. 262 | # The format is a list of tuples containing the path and title. 263 | #epub_post_files = [] 264 | 265 | # A list of files that should not be packed into the epub file. 266 | #epub_exclude_files = [] 267 | 268 | # The depth of the table of contents in toc.ncx. 269 | #epub_tocdepth = 3 270 | 271 | # Allow duplicate toc entries. 272 | #epub_tocdup = True 273 | -------------------------------------------------------------------------------- /doc/source/guidedreview.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Guided Review Process 3 | ===================== 4 | 5 | The API Special Interest Group would like to increase the tools available to 6 | OpenStack project teams by defining a process and venue for conducting live 7 | face-to-face reviews. At a high level, these reviews are focused on the 8 | question "does my project align with the guidelines?" and are intended to be 9 | hosted by the API Special Interest Group at the PTG meetups. 10 | 11 | On a more concrete level, the API Special Interest Group expects that reviews 12 | which are directed towards specific areas, or problems within, an API will 13 | garner the best results (e.g. "Is using a PUT request for updating these 14 | resources appropriate?", "We are using GET requests to start server actions, is 15 | there a better alternative?"). 16 | 17 | Ideal Candidates for Review 18 | --------------------------- 19 | 20 | It may be difficult if not impossible to review the entire API of a project in 21 | a session at the PTG. So here are some suggestions for selecting discussion 22 | topics: 23 | 24 | Is there a part of your API that has generated some disagreement on your 25 | team? If so, that would be an excellent subject for discussion at the PTG. 26 | 27 | Are you unhappy with how some of your current API works? We could brainstorm 28 | ideas about making it more consistent and usable. 29 | 30 | Are you creating a new API? If you're starting a new project, or creating a 31 | new major version for your project, we can discuss what would be the most 32 | effective ways to approach it. 33 | 34 | How do I get my project reviewed? 35 | --------------------------------- 36 | 37 | Here are some things you should prepare before approaching the API working 38 | group for a live review of your project: 39 | 40 | 1. Pick an area of your API to focus on (e.g. a specific resource type, an 41 | interaction that is troublesome or endpoints that could use clarification). 42 | 43 | 2. Prepare a document describing the API in question, this could be free-form 44 | or something more formal like an OpenAPI specification. This does not need 45 | to be an expansive document, but should help drive the review conversation 46 | and provide a reference for the reviewers to understand the flow of the API 47 | in question. 48 | 49 | Then just show up to an API Special Interest Group face-to-face session with 50 | your materials ready. Sending an email ahead of time will help to ensure that 51 | the group is ready for your review but is not strictly necessary. 52 | 53 | What should I expect from my review? 54 | ------------------------------------ 55 | 56 | The answer to this will vary depending on the nature of your request to the 57 | group. You should expect to have clarification on the basic question of how 58 | close your API follows the API-SIG's guidelines. But, the depth of your review 59 | will depend entirely on how big a request is made of the review group. 60 | 61 | The preparations that a project team makes before the review process will have 62 | the largest effect on the expected outcome. Teams that are more specific and 63 | focused with their requests to the review group will most likely harvest the 64 | greatest fruits from this process. 65 | 66 | When considering approaching the API-SIG for a review, we encourage projects to 67 | identify areas of their APIs that could use clarification or have been 68 | problematic to the team. Project teams that have reviewed the API guidelines 69 | and have questions about specific areas of interest will find that their 70 | reviews will be more productive than open-ended questions which cover large 71 | portions of their API. 72 | 73 | After a review is completed, the API Special Interest Group will archive the 74 | general details of the review (e.g. "Team requested a review of API 75 | features and . It was agreed that actions , and are the best 76 | path forward") and any artifacts that are generated during the process. This 77 | archive will exist in the same repository as the guidelines under a separate 78 | heading for reviews. 79 | 80 | Example Review 81 | -------------- 82 | 83 | **TODO** 84 | -------------------------------------------------------------------------------- /doc/source/guidelines: -------------------------------------------------------------------------------- 1 | ../../guidelines -------------------------------------------------------------------------------- /doc/source/index.rst: -------------------------------------------------------------------------------- 1 | .. api-wg documentation master file 2 | 3 | ==================================== 4 | OpenStack API Special Interest Group 5 | ==================================== 6 | 7 | Mission Statement 8 | ----------------- 9 | 10 | To improve the developer experience of API users by converging the OpenStack 11 | API to a consistent and pragmatic RESTful design. The working group creates 12 | guidelines that all OpenStack projects should follow for new development, and 13 | promotes convergence of new APIs and future versions of existing APIs. 14 | 15 | Preamble 16 | -------- 17 | 18 | This document contains the guidelines and rules for OpenStack project 19 | APIs including guidelines and proposed rules concerning API consistency, naming 20 | conventions, and best practice recommendations. 21 | 22 | If you would like to connect with the API Special Interest Group, visit the 23 | wiki at: https://wiki.openstack.org/wiki/API_Special_Interest_Group 24 | 25 | If you are interested in contributing to this document, the git repository is 26 | available at: http://opendev.org/openstack/api-sig/ 27 | 28 | OpenStack code and review submission processes are described at: 29 | http://docs.openstack.org/infra/manual/developers.html 30 | 31 | 32 | .. warning:: 33 | These documents from the API Special Interest Group are primarily focused 34 | on providing advice and guidelines for JSON-based APIs. While other 35 | representations have their place in the OpenStack ecosystem, they present 36 | such a diversity of challenges and edge cases, especially with large and/or 37 | binary request and response bodies, that it is impossible to provide 38 | guidance that is complete. 39 | 40 | .. note:: 41 | Where this guidance is incomplete or ambiguous, refer to the HTTP 42 | RFCs—:rfc:`7230`, :rfc:`7231`, :rfc:`7232`, :rfc:`7233`, :rfc:`7234`, and 43 | :rfc:`7235`—as the ultimate authority. For advice on effectively using 44 | HTTP in APIs see `Building Protocols with 45 | HTTP `_. 46 | 47 | Guidelines 48 | ---------- 49 | 50 | The following topics are related to the working group and its processes: 51 | 52 | .. toctree:: 53 | :glob: 54 | :maxdepth: 1 55 | 56 | process 57 | template 58 | liaisons 59 | guidedreview 60 | 61 | These topics are the API guidance approved by the OpenStack community 62 | and published by the working group: 63 | 64 | .. toctree:: 65 | :glob: 66 | :maxdepth: 1 67 | 68 | guidelines/* 69 | -------------------------------------------------------------------------------- /doc/source/liaisons.json: -------------------------------------------------------------------------------- 1 | { 2 | "liaisons": [ 3 | { 4 | "project": "Barbican", 5 | "name": "Douglas Mendizábal", 6 | "email": "douglas.mendizabal@rackspace.com", 7 | "nick": "redrobot" 8 | }, 9 | { 10 | "project": "Ceilometer", 11 | "name": "Chris Dent", 12 | "email": "cdent+os@anticedent.org", 13 | "nick": "cdent" 14 | }, 15 | { 16 | "project": "Cinder", 17 | "name": "Scott DAngelo", 18 | "email": "scott.dangelo@gmail.com", 19 | "nick": "scottda" 20 | }, 21 | { 22 | "project": "Congress", 23 | "name": "Masahito Muroi", 24 | "email": "muroi.masahito@lab.ntt.co.jp", 25 | "nick": "masahito" 26 | }, 27 | { 28 | "project": "Designate", 29 | "name": "", 30 | "email": "", 31 | "nick": "" 32 | }, 33 | { 34 | "project": "Glance", 35 | "name": "Nikhil Komawar", 36 | "email": "nik.komawar@gmail.com", 37 | "nick": "nikhil_k" 38 | }, 39 | { 40 | "project": "Heat", 41 | "name": "Rico Lin", 42 | "email": "ricolin@ricolky.com", 43 | "nick": "ricolin" 44 | }, 45 | { 46 | "project": "Horizon", 47 | "name": "Cindy Lu", 48 | "email": "clu@us.ibm.com", 49 | "nick": "clu_" 50 | }, 51 | { 52 | "project": "Ironic", 53 | "name": "Vladyslav Drok", 54 | "email": "vdrok@mirantis.com", 55 | "nick": "vdrok" 56 | }, 57 | { 58 | "project": "Keystone", 59 | "name": "Colleen Murphy", 60 | "email": "colleen@gazlene.net", 61 | "nick": "cmurphy" 62 | }, 63 | { 64 | "project": "MagnetoDB", 65 | "name": "Ilya Sviridov", 66 | "email": "sviridov.ilya@gmail.com", 67 | "nick": "isviridov" 68 | }, 69 | { 70 | "project": "Magnum", 71 | "name": "Eli Qiao", 72 | "email": "liyong.qiao@intel.com", 73 | "nick": "eliqiao" 74 | }, 75 | { 76 | "project": "Magnum", 77 | "name": "Hua Wang", 78 | "email": "wanghua.humble@gmail.com", 79 | "nick": "wanghua" 80 | }, 81 | { 82 | "project": "Manila", 83 | "name": "Goutham Pacha Ravi", 84 | "email": "Goutham.PachaRavi@netapp.com", 85 | "nick": "gouthamr" 86 | }, 87 | { 88 | "project": "Mistral", 89 | "name": "Renat Akhmerov", 90 | "email": "renat.akhmerov@gmail.com", 91 | "nick": "rakhmerov" 92 | }, 93 | { 94 | "project": "Murano", 95 | "name": "Nikolay Starodubtsev", 96 | "email": "nstarodubstev@mirantis.com", 97 | "nick": "Nikolay_St" 98 | }, 99 | { 100 | "project": "Neutron", 101 | "name": "Akihiro Motoki", 102 | "email": "amotoki@gmail.com", 103 | "nick": "amotoki" 104 | }, 105 | { 106 | "project": "Nova", 107 | "name": "Alex Xu", 108 | "email": "soulxu@gmail.com", 109 | "nick": "alex_xu" 110 | }, 111 | { 112 | "project": "Placement", 113 | "name": "Ed Leafe", 114 | "email": "ed@leafe.com", 115 | "nick": "edleafe" 116 | }, 117 | { 118 | "project": "Rally", 119 | "name": "", 120 | "email": "", 121 | "nick": "" 122 | }, 123 | { 124 | "project": "Sahara", 125 | "name": "Michael McCune", 126 | "email": "msm@redhat.com", 127 | "nick": "elmiko" 128 | }, 129 | { 130 | "project": "Senlin", 131 | "name": "Qiming Teng", 132 | "email": "tengqim@linux.vnet.ibm.com", 133 | "nick": "Qiming" 134 | }, 135 | { 136 | "project": "Swift", 137 | "name": "John Dickinson", 138 | "email": "me@not.mn", 139 | "nick": "notmyname" 140 | }, 141 | { 142 | "project": "Trove", 143 | "name": "Peter Stachowski", 144 | "email": "peter@tesora.com", 145 | "nick": "peterstac" 146 | }, 147 | { 148 | "project": "Trove", 149 | "name": "Amrith Kumar", 150 | "email": "amrith.kumar@gmail.com", 151 | "nick": "amrith" 152 | }, 153 | { 154 | "project": "Tripleo", 155 | "name": "", 156 | "email": "", 157 | "nick": "" 158 | }, 159 | { 160 | "project": "Zaqar", 161 | "name": "Fei Long Wang", 162 | "email": "feilong@catalyst.net.nz", 163 | "nick": "flwang" 164 | } 165 | ] 166 | } 167 | -------------------------------------------------------------------------------- /doc/source/liaisons.rst: -------------------------------------------------------------------------------- 1 | Cross-Project Liaisons 2 | ====================== 3 | 4 | Description 5 | ----------- 6 | 7 | The API Special Interest Group seeks API subject matter experts for each 8 | project to communicate plans for API updates, review API guidelines with their 9 | project's view in mind, and review the API Special Interest Group guidelines as 10 | they are drafted. The Cross-Project Liaison (CPL) should be familiar with the 11 | project's REST API design and future planning for changes to it. 12 | 13 | * The liaison should be the PTL or whomever they delegate to be their 14 | representative 15 | * The liaison is the first line of contact for the API Special Interest Group 16 | team members 17 | * The liaison may further delegate work to other subject matter experts 18 | * The liaison should be aware of and engaged in the API Special Interest Group 19 | `Communication channels 20 | `_ 21 | * The Nova team has been very explicit about how they will liaise with the 22 | API Special Interest Group; see the `Responsibilities of Liaisons `_ 23 | 24 | Tooling 25 | ------- 26 | 27 | To make it easier to engage the liaisons, we have a tool that will add all 28 | current liaisons to an API WG review. 29 | 30 | You can run the tool like so from the base dir of the api-wg repository. 31 | 32 | :: 33 | 34 | $ python3 tools/add-reviewers.py my-gerrit-username 183599 35 | Added 21 reviewers to 183599 36 | 37 | To get help use ``--help``. 38 | 39 | :: 40 | 41 | $ python3 tools/add-reviewers.py --help 42 | 43 | Liaisons 44 | -------- 45 | 46 | .. literalinclude:: liaisons.json 47 | :language: json 48 | -------------------------------------------------------------------------------- /doc/source/process.rst: -------------------------------------------------------------------------------- 1 | ========================================= 2 | Process for adding or changing guidelines 3 | ========================================= 4 | 5 | This document describes the process we will use before merging a non 6 | trivial changeset in the guidelines directory. A non trivial changeset 7 | is one which is more than a spelling/grammar typo or reformatting 8 | change. 9 | 10 | The guidelines are initially intended to be a group draft document. Our intent 11 | is to move fairly quickly to get published draft guidelines so this process 12 | reflects a preference for efficiency while gathering consensus. 13 | 14 | Review process 15 | -------------- 16 | 17 | For trivial changes (as defined above) there is no minimum time that they must 18 | be proposed before merging. They must have at least one +1 vote other than the 19 | approver and no -1. Once this is true a working group core may merge the 20 | change. 21 | 22 | For changes which add a new guideline or make substantial changes to an 23 | existing guideline reaching consensus is an explicit goal. To that end there is 24 | a well defined process to ensure that proposals receive adequate review by the 25 | API Special Interest Group, cross project liaisons, and the OpenStack community 26 | at large. 27 | 28 | In the various stages of the review process (defined below) consensus means the 29 | changeset is in its near final form for at least two working days. Minor 30 | typo/formatting changes do not reset the counter. There must be at least four 31 | +1 votes and no -1 votes unless the concern related to the -1 vote has been 32 | discussed in an API WG meeting. Once the matter has been discussed there should 33 | be no more than 20% of votes cast as -1 votes. 34 | 35 | Discussion on Gerrit should be encouraged as the primary response. When 36 | discussion on IRC (in meetings or otherwise) is required that discussion should 37 | be summarized back to Gerrit. 38 | 39 | That process is: 40 | 41 | 1. API Special Interest Group members should review proposed guideline changes 42 | and reach consensus. 43 | 44 | 2. When consensus is reached within the group the guideline should be marked as 45 | *frozen* and cross project liaisons (CPLs) should be invited to review the 46 | guideline. There is an ``add-reviewers.py`` script to do this. See 47 | :doc:`liaisons` for more information. 48 | 49 | A proposal can be frozen by exactly one core reviewer by setting Code-Review 50 | +2. Only the core reviewer responsible for freezing the proposal should +2 51 | it. All other core reviewers should vote with at most a +1 when reviewing. 52 | 53 | 3. The CPLs have one week to review the proposal. If there are no reviews lazy 54 | consensus is assumed. If there is a -1 review by a CPL that requires an 55 | update to the changeset, it does not reset the 1 week the CPLs have to 56 | review it. 57 | 58 | 4. When there is consensus from the CPLs, the proposal may be merged. 59 | 60 | To avoid opportunities for miscommunication, the core working group member 61 | who froze the changeset should be responsible for merging it. If that core 62 | is unavailable for enough time to cause a delay then the responsibility 63 | falls to one of the others cores. 64 | 65 | An email should be sent to the openstack-dev mailing list containing the 66 | links to all of the guidelines that have recently merged. The finalized 67 | guidelines should be buffered such that a maximum of one announcement email 68 | is sent per week. 69 | 70 | If at any time during this process there is difficulty reaching consensus or an 71 | apparent lack of information or input, additional input should be sought from 72 | the rest of the community. Two ways to do this include (preferring email): 73 | 74 | 1. The openstack-dev mailing list. An email may be sent to the openstack-dev 75 | mailing list with the subject "[all][api] New API Guidelines Ready for Cross 76 | Project Review". The email should contain links to the guidelines that need 77 | additional input. 78 | 79 | 2. The `Cross Project Meeting 80 | `_. An agenda 81 | item should be added to the Cross Project Meeting which indicates need for 82 | discussion. Links to the guidelines that need additional input should be 83 | provided. When this is done an API WG member must attend the meeting to 84 | highlight the agenda item. 85 | 86 | Merged guidelines comprise a draft of the official guidelines. Before an 87 | official version of the guidelines can be released the following has to occur: 88 | 89 | * An 80% (of votes cast) majority vote on the document as a whole with one vote 90 | per OpenStack PTL (or delegate). 91 | 92 | * Reviewed and approved by the TC. The API WG is a delegated group from the TC 93 | so the TC ultimately get final say on what the working group are able to 94 | release. 95 | 96 | Proposing a new guideline 97 | ------------------------- 98 | 99 | When proposing a new guideline you should start by using the :doc:`guideline 100 | template