Greetings OpenStack community,
In today's meeting [0] after briefly covering old business we spent nearly 50 minutes
going round in circles discussing the complex interactions of expectations of API
stability, the need to fix bugs and the costs and benefits of microversions. We didn't
make a lot of progress on the general issues, but we did #agree that a glance issue [4]
should be treated as a code bug (not a documentation bug) that should be fixed. In some
ways this position is not aligned with the ideal presented by stability guidelines but it
is aligned with an original goal of the API-WG: consistency. It's unclear how to resolve
this conflict, either in this specific instance or in the guidelines that the API-WG
creates. As stated in response to one of the related reviews [5]: "If bugs like this
don't get fixed properly in the code, OpenStack risks going down the path of Internet
Explorer and people wind up writing client code to the bugs and that way lies
madness."
One reminder: Projects should make sure that their liaison information is up to
date at http://specs.openstack.org/openstack/api-wg/liaisons.html . If not,
please provide a patch to doc/source/liaisons.json to update it.
Three guidelines were merged. None were frozen. Four are being worked on. See
below.
# Newly Published Guidelines
* Add guideline for invalid query parameters
https://review.openstack.org/#/c/417441/
* Add guidelines on usage of state vs. status
https://review.openstack.org/#/c/411528/
* Clarify the status values in versions
https://review.openstack.org/#/c/411849/
# API Guidelines Proposed for Freeze
Guidelines that are ready for wider review by the whole community.
Nothing newly frozen.
# Guidelines Currently Under Review [3]
* Add guidelines for boolean names
https://review.openstack.org/#/c/411529/
* Define pagination guidelines
https://review.openstack.org/#/c/390973/
* Add API capabilities discovery guideline
https://review.openstack.org/#/c/386555/
* [WIP] Refactor and re-validate api change guidelines
https://review.openstack.org/#/c/421846/
# Highlighting your API impacting issues
If you seek further review and insight from the API WG, please address your concerns in
an email to the OpenStack developer mailing list[1] with the tag "[api]" in the
subject. In your email, you should include any relevant reviews, links, and comments to
help guide the discussion of the specific challenge you are facing.
To learn more about the API WG mission and the work we do, see OpenStack API
Working Group [2].
Thanks for reading and see you next week!
# References
[0]
http://eavesdrop.openstack.org/meetings/api_wg/2017/api_wg.2017-02-02-16.00.html
[1] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[2] http://specs.openstack.org/openstack/api-wg/
[3] https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
[4] https://bugs.launchpad.net/glance/+bug/1656183
[5] https://review.openstack.org/#/c/425487/
Meeting Agenda
https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
Past Meeting Records
http://eavesdrop.openstack.org/meetings/api_wg/
Open Bugs
https://bugs.launchpad.net/openstack-api-wg
--
Chris Dent ¯\_(ツ)_/¯ https://anticdent.org/
freenode: cdent tw: @anticdent
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
