[all][api-sig] Update on SIG status and seeking guidance from the community
hello all, I am writing on behalf of the API-SIG to update the community on our status. We have recently learned that Ed Leafe will be leaving the membership of the SIG as his new working circumstances are pulling him away from this work. This will leave us with only 2 active members, Dmitry Tantsur and myself. Firstly, I want to extend a heartfelt thanks to Ed. thank you =) I believe that Ed is the longest standing member of the SIG, having been active from the days when it was just a smol working group. His contributions have been numerous over the years and his guidance and wisdom will be missed. Second, this change in our membership has given rise to some questions about the future of the SIG and how we might best serve the OpenStack community. We currently hold an office hour each week and see relatively low traffic during this hour. Our activities have mainly been focused on writing and maintaining the guidelines and the support structure around those guidelines. As most of the new writing has ended (there are a few still in flight), we have been paying most of our attention to maintenance and supporting the community. As our ability to maintain an active membership has diminished, and many of our initial goals met, we have started to question whether we should still maintain the "SIG" status and also how we might best serve the community going forward. We will still need core members to review and approve changes, but perhaps we should adjust our workflow to be of greater service. I don't have any answers to this more existential question about the SIG, but we as a group felt it was a good idea to reach out to the wider community for advice and guidance. So, what do you all have to say? What would you like to see from the API-SIG moving forward? Should we re-evaluate the purpose of this group and how it relates to the OpenStack community? thank you all for the wonderful spirit of openness that we build with, and thanks for listening. and lastly, thanks again to Ed. You have acted as an example of the best aspects of open collaboration. peace o/
Michael McCune wrote:
[...] I don't have any answers to this more existential question about the SIG, but we as a group felt it was a good idea to reach out to the wider community for advice and guidance. So, what do you all have to say? What would you like to see from the API-SIG moving forward? Should we re-evaluate the purpose of this group and how it relates to the OpenStack community? [...]
Thanks for starting this thread, Michael. Just because something was needed at one point in our history does not mean we need to continue doing it forever, so reevaluating periodically is important. The API WG was originally formed to (1) provide guidelines for API design for project teams to follow, and (2) improve API user experience by converging the OpenStack APIs to be consistent. It was then converted to a SIG, but the original purpose remained. Would you say that those goals have been completed? Are the documented guidelines sufficiently complete to be usable? Is the resulting API user experience sufficiently consistent? If not, maybe this is an opportunity to recruit, by painting a desirable common goal, maybe leveraging the "community goals" process to achieve incremental, baby-steps improvements within the scope of a release cycle. Personally I think it's always good to have a group of API design experts that project teams can tap into when they have questions on good API design. I just have no idea how often such advice is actually asked for. How often do you get questions on API design from projects adding features to their API? Would you say that when a new project adds an API, it is well-designed, or it would have benefited from your advice? Cheers, -- Thierry Carrez (ttx)
On Fri, Aug 23, 2019 at 4:28 AM Thierry Carrez <thierry@openstack.org> wrote:
Michael McCune wrote:
[...] I don't have any answers to this more existential question about the SIG, but we as a group felt it was a good idea to reach out to the wider community for advice and guidance. So, what do you all have to say? What would you like to see from the API-SIG moving forward? Should we re-evaluate the purpose of this group and how it relates to the OpenStack community? [...]
Thanks for starting this thread, Michael. Just because something was needed at one point in our history does not mean we need to continue doing it forever, so reevaluating periodically is important.
The API WG was originally formed to (1) provide guidelines for API design for project teams to follow, and (2) improve API user experience by converging the OpenStack APIs to be consistent. It was then converted to a SIG, but the original purpose remained.
Would you say that those goals have been completed? Are the documented guidelines sufficiently complete to be usable? Is the resulting API user experience sufficiently consistent? If not, maybe this is an opportunity to recruit, by painting a desirable common goal, maybe leveraging the "community goals" process to achieve incremental, baby-steps improvements within the scope of a release cycle.
i think the questions you lead with are excellent, and definitely something that we as a SIG, and community, should consider. although i feel quite good about the current state of the guidelines i'm sure there is room for improvement, but i think the question about the resulting API user experience is quite poignant. these are topics we are definitely bringing up for Ed's last meeting next week ;)
Personally I think it's always good to have a group of API design experts that project teams can tap into when they have questions on good API design. I just have no idea how often such advice is actually asked for. How often do you get questions on API design from projects adding features to their API? Would you say that when a new project adds an API, it is well-designed, or it would have benefited from your advice?
these days, the rate of questions to the group has slowed but there are still times when we get called up (maybe once a month or less). i agree that having a group of experienced API engineers /does/ help the broader community, i think the tough part to evaluate is the impact we have on a day-to-day basis. in the past i have experienced first hand the effects of the API SIG and i have usually been very pleased and delighted that the group had such a wide reach. within the last few years though i have not had as much direct contact, it has mainly been through SIG meetings. i really appreciate the questions you are posing, i don't think i have good answers for them but i believe the SIG should put some time into thinking about, and answering, them. thanks again for the thoughtful comments =) peace o/
Cheers,
-- Thierry Carrez (ttx)
feel quite good about the current state of the guidelines i'm sure there is room for improvement,
It's worth noting that there's quite a lot of unmerged guideline content under the api-sig's purview [1]. We should either close or rehome these patches before we consider disbanding the SIG. It's obviously hard to merge stuff with a small (and now shrinking) core list [2], but at least some of this content is valuable and should not be abandoned. I, for one, would like to be able to refer to published documentation rather than in-flight (or abandoned) change sets when wrestling with version discovery logic in ksa/sdk. efried [1] https://review.opendev.org/#/q/project:openstack/api-sig+status:open [2] https://review.opendev.org/#/admin/groups/468,members
On Fri, Aug 23, 2019 at 9:58 AM Eric Fried <openstack@fried.cc> wrote:
feel quite good about the current state of the guidelines i'm sure there is room for improvement,
It's worth noting that there's quite a lot of unmerged guideline content under the api-sig's purview [1]. We should either close or rehome these patches before we consider disbanding the SIG. It's obviously hard to merge stuff with a small (and now shrinking) core list [2], but at least some of this content is valuable and should not be abandoned. I, for one, would like to be able to refer to published documentation rather than in-flight (or abandoned) change sets when wrestling with version discovery logic in ksa/sdk.
++ we should make it a priority to re-visit these and do triage where necessary. thank you peace o/
efried
[1] https://review.opendev.org/#/q/project:openstack/api-sig+status:open [2] https://review.opendev.org/#/admin/groups/468,members
---- On Fri, 23 Aug 2019 22:55:06 +0900 Eric Fried <openstack@fried.cc> wrote ----
feel quite good about the current state of the guidelines i'm sure there is room for improvement,
It's worth noting that there's quite a lot of unmerged guideline content under the api-sig's purview [1]. We should either close or rehome these patches before we consider disbanding the SIG. It's obviously hard to merge stuff with a small (and now shrinking) core list [2], but at least some of this content is valuable and should not be abandoned. I, for one, would like to be able to refer to published documentation rather than in-flight (or abandoned) change sets when wrestling with version discovery logic in ksa/sdk.
In addition, there are many TODO also there in current guidelines [1]. Few of them I remember were left as TODO when few guidelines were moved from nova to api-wg. [1] https://github.com/openstack/api-sig/search?q=TODO&unscoped_q=TODO -gmann
efried
[1] https://review.opendev.org/#/q/project:openstack/api-sig+status:open [2] https://review.opendev.org/#/admin/groups/468,members
On Sat, Aug 24, 2019 at 5:52 AM Ghanshyam Mann <gmann@ghanshyammann.com> wrote:
---- On Fri, 23 Aug 2019 22:55:06 +0900 Eric Fried <openstack@fried.cc> wrote ----
feel quite good about the current state of the guidelines i'm sure there is room for improvement,
It's worth noting that there's quite a lot of unmerged guideline content under the api-sig's purview [1]. We should either close or rehome these patches before we consider disbanding the SIG. It's obviously hard to merge stuff with a small (and now shrinking) core list [2], but at least some of this content is valuable and should not be abandoned. I, for one, would like to be able to refer to published documentation rather than in-flight (or abandoned) change sets when wrestling with version discovery logic in ksa/sdk.
In addition, there are many TODO also there in current guidelines [1]. Few of them I remember were left as TODO when few guidelines were moved from nova to api-wg.
[1] https://github.com/openstack/api-sig/search?q=TODO&unscoped_q=TODO
that's a good highlight, thank you for the link. perhaps a good next step will to be collect all the pointers to work that needs finishing and figure out if we can triage it and plan some sort of schedule for fixing it. i imagine it will be slow given the current staffing, but we could at least point people at things to look for if they want to help. peace o/
-gmann
efried
[1] https://review.opendev.org/#/q/project:openstack/api-sig+status:open [2] https://review.opendev.org/#/admin/groups/468,members
On Mon, 26 Aug 2019, Michael McCune wrote:
On Sat, Aug 24, 2019 at 5:52 AM Ghanshyam Mann <gmann@ghanshyammann.com> wrote:
In addition, there are many TODO also there in current guidelines [1]. Few of them I remember were left as TODO when few guidelines were moved from nova to api-wg.
[1] https://github.com/openstack/api-sig/search?q=TODO&unscoped_q=TODO
that's a good highlight, thank you for the link.
perhaps a good next step will to be collect all the pointers to work that needs finishing and figure out if we can triage it and plan some sort of schedule for fixing it. i imagine it will be slow given the current staffing, but we could at least point people at things to look for if they want to help.
I think it's important to keep in mind that if we've had those TODOs for so long, many of them for much longer than 3 years, it is quite likely they aren't to dos, but instead are to don't: things people neither care about nor need. At least not enough to do anything about. Keeping the API-SIG on life support to address TODOs that old seems like make-work to me. It's time to start trimming the optional stuff and focus only on the things for which there is real user or developer demand [1]. Not just in the API-SIG but across all of OpenStack. [1] "Vendors" left out on purpose. -- Chris Dent ٩◔̯◔۶ https://anticdent.org/ freenode: cdent
On Tue, Aug 27, 2019 at 4:21 AM Chris Dent <cdent+os@anticdent.org> wrote:
On Mon, 26 Aug 2019, Michael McCune wrote:
On Sat, Aug 24, 2019 at 5:52 AM Ghanshyam Mann <gmann@ghanshyammann.com> wrote:
In addition, there are many TODO also there in current guidelines [1]. Few of them I remember were left as TODO when few guidelines were moved from nova to api-wg.
[1] https://github.com/openstack/api-sig/search?q=TODO&unscoped_q=TODO
that's a good highlight, thank you for the link.
perhaps a good next step will to be collect all the pointers to work that needs finishing and figure out if we can triage it and plan some sort of schedule for fixing it. i imagine it will be slow given the current staffing, but we could at least point people at things to look for if they want to help.
I think it's important to keep in mind that if we've had those TODOs for so long, many of them for much longer than 3 years, it is quite likely they aren't to dos, but instead are to don't: things people neither care about nor need. At least not enough to do anything about.
agreed
Keeping the API-SIG on life support to address TODOs that old seems like make-work to me. It's time to start trimming the optional stuff and focus only on the things for which there is real user or developer demand [1]. Not just in the API-SIG but across all of OpenStack.
also agreed, this is why i think it would be nice to do a triage on the api-sig issues and just figure out what we will want to fix and what is likely just old kruft. peace o/
[1] "Vendors" left out on purpose.
-- Chris Dent ٩◔̯◔۶ https://anticdent.org/ freenode: cdent
participants (5)
-
Chris Dent
-
Eric Fried
-
Ghanshyam Mann
-
Michael McCune
-
Thierry Carrez