Re: [openstack-dev] [api] Forming the API Working Group
On Wed, Oct 15, 2014 at 7:44 AM, Christopher Yeoh wrote: > On Tue, 14 Oct 2014 09:45:44 -0400 > Jay Pipes wrote: > > > On 10/14/2014 12:52 AM, Christopher Yeoh wrote: > > > On Mon, 13 Oct 2014 22:20:32 -0400 > > > Jay Pipes wrote: > > > > > >> On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > > >>> On Mon, 13 Oct 2014 10:52:26 -0400 > > > And whilst I don't have a problem with having some guidelines which > > > suggest a future standard for APIs, I don't think we should be > > > requiring any type of feature which has not yet been implemented in > > > at least one, preferably two openstack projects and released and > > > tested for a cycle. Eg standards should be lagging rather than > > > leading. > > > > What about "features" in some of our APIs that are *not* preferable? > > For instance: API extensions. > > > > I think we've seen where API extensions leads us. And it isn't > > pretty. Would you suggest we document what a Nova API extension or a > > Neutron API extension looks like and then propose, for instance, not > > to ever do it again in future APIs and instead use schema > > discoverability? > > So if we had standards leading development rather than lagging in the > past then API extensions would have ended up in the standard because we > once thought they were a good idea. > > Perhaps we should distinguish in the documentation between > recommendations (future looking) and standards (proven it works well > for us). The latter would be potentially enforced a lot more strictly > than the former. > That will be great to have classification in guidelines (Strict , recommended etc ) and step by step those can be moved to higher classification as project start consuming those. > In the case of extensions I think we should have a section documenting > why we think they're a bad idea and new projects certainly shouldn't > use them. But also give some advice around if they are used what > features they should have (eg version numbers!). Given the time that it > takes to make major API infrastructure changes it is inevitable that > there will be api extensions added in the short to medium term. Because > API development will not just stop while API infrastructure is improved. > > > > I think it will be better in git (but we also need it in gerrit) > > > when it comes to resolving conflicts and after we've established a > > > decent document (eg when we have more content). I'm just looking to > > > make it as easy as possible for anyone to add any guidelines now. > > > Once we've actually got something to discuss then we use git/gerrit > > > with patches proposed to resolve conflicts within the document. > > > > Of course it would be in Gerrit. I just put it up on GitHub first > > because I can't just add a repo into the openstack/ code > > namespace... :) > > I've submitted a patch to add an api-wg project using your repository > as the initial content for the git repository. > > https://review.openstack.org/#/c/128466/ > > Regards, > > Chris > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > -- Thanks & Regards Ghanshyam Mann ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 2014年10月14日 21:57, Jay Pipes wrote: On 10/14/2014 05:04 AM, Alex Xu wrote: There is one reason to think about what projects *currently* do. When we choice which convention we want. For example, the CamelCase and snake_case, if the most project use snake_case, then choice snake_case style will be the right. I would posit that the reason we have such inconsistencies in our project's APIs is that we haven't taken a stand and said "this is the way it must be". There's lots of examples of inconsistencies out in the OpenStack APIs. We can certainly use a wiki or etherpad page to document those inconsistencies. But, eventually, this working group should produce solid decisions that should be enforced across *future* OpenStack APIs. And that guidance should be forthcoming in the next month or so, not in one or two release cycles. I personally think proposing patches to an openstack-api repository is the most effective way to make those proposals. Etherpads and wiki pages are fine for dumping content, but IMO, we don't need to dump content -- we already have plenty of it. We need to propose guidelines for *new* APIs to follow. +1 in the next month, stop more inconsistent. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
Hi all, to my understanding we certainly don't want developers to arbitrarily extend APIs which would lead to a lot of mess, however we still need to find a way to standardize how we augment existing APIs since they are not perfect either. On Wed, Oct 15, 2014 at 7:02 AM, Doug Hellmann wrote: > > On Oct 14, 2014, at 6:00 PM, Lance Bragstad wrote: > > > > On Tue, Oct 14, 2014 at 4:29 PM, Christopher Yeoh > wrote: > >> On Tue, 14 Oct 2014 10:29:34 -0500 >> Lance Bragstad wrote: >> >> > I found a couple of free times available for a weekly meeting if >> > people are interested: >> > >> > https://review.openstack.org/#/c/128332/2 >> > >> > Not sure if a meeting time has been hashed out already or not, and if >> > it has I'll change the patch accordingly. If not, we can iterate on >> > possible meeting times in the review if needed. This was to just get >> > the ball rolling if we want a weekly meeting. I proposed one review >> > for Thursdays at 2100 and a second patch set for 2000, UTC. That can >> > easily change, but those were two times that didn't conflict with the >> > existing meeting schedules in #openstack-meeting. >> >> So UTC 2000 is 7am Sydney, 5am Tokyo and 4am Beijing time which is >> pretty early in the day. I'd suggest UTC if that's not too late for >> others who'd like to participate. >> >> Chris >> > > Unfortunately, we conflict with the I18N Team Meeting at UTC (in > #openstack-meeting). I updated the review for UTC 1000. An alternating > schedule would probably work well given the attendance from different times > zones. I'll snoop around for another meeting time to alternate with, unless > someone has one in mind. > > > Don’t forget about #openstack-meeting-alt and #openstack-meeting-3 as > alternative rooms for the meetings. Those have the meeting bot and are > managed on the same wiki page for scheduling. > > Doug > > > >> >> >> > >> > >> > >> > On Tue, Oct 14, 2014 at 3:55 AM, Thierry Carrez >> > wrote: >> > >> > > Jay Pipes wrote: >> > > > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: >> > > >> I guess we could also start fleshing out in the repo how we'll >> > > >> work in practice too (eg once the document is stable what >> > > >> process do we have for making changes - two +2's is probably not >> > > >> adequate for something like this). >> > > > >> > > > We can make it work exactly like the openstack/governance repo, >> > > > where ttx has the only ability to +2/+W approve a patch for >> > > > merging, and he tallies a majority vote from the TC members, who >> > > > vote -1 or +1 on a proposed patch. >> > > > >> > > > Instead of ttx, though, we can have an API working group lead >> > > > selected from the set of folks currently listed as committed to >> > > > the effort? >> > > >> > > Yes, the working group should select a "chair" who would fill the >> > > same role I do for the TC (organize meetings, push agenda, tally >> > > votes on reviews, etc.) >> > > >> > > That would be very helpful in keeping that diverse group on track. >> > > Now you just need some volunteer :) >> > > >> > > -- >> > > Thierry Carrez (ttx) >> > > >> > > ___ >> > > OpenStack-dev mailing list >> > > OpenStack-dev@lists.openstack.org >> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > >> >> >> ___ >> OpenStack-dev mailing list >> OpenStack-dev@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > -- Zhipeng Huang Research Assistant Mobile Ad-Hoc Network Lab, Calit2 University of California, Irvine Email: zhipe...@uci.edu Office: Calit2 Building Room 2402 OpenStack, OpenDaylight, OpenCompute affcienado ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Oct 14, 2014, at 6:00 PM, Lance Bragstad wrote: > > > On Tue, Oct 14, 2014 at 4:29 PM, Christopher Yeoh wrote: > On Tue, 14 Oct 2014 10:29:34 -0500 > Lance Bragstad wrote: > > > I found a couple of free times available for a weekly meeting if > > people are interested: > > > > https://review.openstack.org/#/c/128332/2 > > > > Not sure if a meeting time has been hashed out already or not, and if > > it has I'll change the patch accordingly. If not, we can iterate on > > possible meeting times in the review if needed. This was to just get > > the ball rolling if we want a weekly meeting. I proposed one review > > for Thursdays at 2100 and a second patch set for 2000, UTC. That can > > easily change, but those were two times that didn't conflict with the > > existing meeting schedules in #openstack-meeting. > > So UTC 2000 is 7am Sydney, 5am Tokyo and 4am Beijing time which is > pretty early in the day. I'd suggest UTC if that's not too late for > others who'd like to participate. > > Chris > > Unfortunately, we conflict with the I18N Team Meeting at UTC (in > #openstack-meeting). I updated the review for UTC 1000. An alternating > schedule would probably work well given the attendance from different times > zones. I'll snoop around for another meeting time to alternate with, unless > someone has one in mind. Don’t forget about #openstack-meeting-alt and #openstack-meeting-3 as alternative rooms for the meetings. Those have the meeting bot and are managed on the same wiki page for scheduling. Doug > > > > > > > > > > > On Tue, Oct 14, 2014 at 3:55 AM, Thierry Carrez > > wrote: > > > > > Jay Pipes wrote: > > > > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > > > >> I guess we could also start fleshing out in the repo how we'll > > > >> work in practice too (eg once the document is stable what > > > >> process do we have for making changes - two +2's is probably not > > > >> adequate for something like this). > > > > > > > > We can make it work exactly like the openstack/governance repo, > > > > where ttx has the only ability to +2/+W approve a patch for > > > > merging, and he tallies a majority vote from the TC members, who > > > > vote -1 or +1 on a proposed patch. > > > > > > > > Instead of ttx, though, we can have an API working group lead > > > > selected from the set of folks currently listed as committed to > > > > the effort? > > > > > > Yes, the working group should select a "chair" who would fill the > > > same role I do for the TC (organize meetings, push agenda, tally > > > votes on reviews, etc.) > > > > > > That would be very helpful in keeping that diverse group on track. > > > Now you just need some volunteer :) > > > > > > -- > > > Thierry Carrez (ttx) > > > > > > ___ > > > OpenStack-dev mailing list > > > OpenStack-dev@lists.openstack.org > > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Tue, 14 Oct 2014 09:45:44 -0400 Jay Pipes wrote: > On 10/14/2014 12:52 AM, Christopher Yeoh wrote: > > On Mon, 13 Oct 2014 22:20:32 -0400 > > Jay Pipes wrote: > > > >> On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > >>> On Mon, 13 Oct 2014 10:52:26 -0400 > > And whilst I don't have a problem with having some guidelines which > > suggest a future standard for APIs, I don't think we should be > > requiring any type of feature which has not yet been implemented in > > at least one, preferably two openstack projects and released and > > tested for a cycle. Eg standards should be lagging rather than > > leading. > > What about "features" in some of our APIs that are *not* preferable? > For instance: API extensions. > > I think we've seen where API extensions leads us. And it isn't > pretty. Would you suggest we document what a Nova API extension or a > Neutron API extension looks like and then propose, for instance, not > to ever do it again in future APIs and instead use schema > discoverability? So if we had standards leading development rather than lagging in the past then API extensions would have ended up in the standard because we once thought they were a good idea. Perhaps we should distinguish in the documentation between recommendations (future looking) and standards (proven it works well for us). The latter would be potentially enforced a lot more strictly than the former. In the case of extensions I think we should have a section documenting why we think they're a bad idea and new projects certainly shouldn't use them. But also give some advice around if they are used what features they should have (eg version numbers!). Given the time that it takes to make major API infrastructure changes it is inevitable that there will be api extensions added in the short to medium term. Because API development will not just stop while API infrastructure is improved. > > I think it will be better in git (but we also need it in gerrit) > > when it comes to resolving conflicts and after we've established a > > decent document (eg when we have more content). I'm just looking to > > make it as easy as possible for anyone to add any guidelines now. > > Once we've actually got something to discuss then we use git/gerrit > > with patches proposed to resolve conflicts within the document. > > Of course it would be in Gerrit. I just put it up on GitHub first > because I can't just add a repo into the openstack/ code > namespace... :) I've submitted a patch to add an api-wg project using your repository as the initial content for the git repository. https://review.openstack.org/#/c/128466/ Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Tue, Oct 14, 2014 at 4:29 PM, Christopher Yeoh wrote: > On Tue, 14 Oct 2014 10:29:34 -0500 > Lance Bragstad wrote: > > > I found a couple of free times available for a weekly meeting if > > people are interested: > > > > https://review.openstack.org/#/c/128332/2 > > > > Not sure if a meeting time has been hashed out already or not, and if > > it has I'll change the patch accordingly. If not, we can iterate on > > possible meeting times in the review if needed. This was to just get > > the ball rolling if we want a weekly meeting. I proposed one review > > for Thursdays at 2100 and a second patch set for 2000, UTC. That can > > easily change, but those were two times that didn't conflict with the > > existing meeting schedules in #openstack-meeting. > > So UTC 2000 is 7am Sydney, 5am Tokyo and 4am Beijing time which is > pretty early in the day. I'd suggest UTC if that's not too late for > others who'd like to participate. > > Chris > Unfortunately, we conflict with the I18N Team Meeting at UTC (in #openstack-meeting). I updated the review for UTC 1000. An alternating schedule would probably work well given the attendance from different times zones. I'll snoop around for another meeting time to alternate with, unless someone has one in mind. > > > > > > > > > > On Tue, Oct 14, 2014 at 3:55 AM, Thierry Carrez > > wrote: > > > > > Jay Pipes wrote: > > > > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > > > >> I guess we could also start fleshing out in the repo how we'll > > > >> work in practice too (eg once the document is stable what > > > >> process do we have for making changes - two +2's is probably not > > > >> adequate for something like this). > > > > > > > > We can make it work exactly like the openstack/governance repo, > > > > where ttx has the only ability to +2/+W approve a patch for > > > > merging, and he tallies a majority vote from the TC members, who > > > > vote -1 or +1 on a proposed patch. > > > > > > > > Instead of ttx, though, we can have an API working group lead > > > > selected from the set of folks currently listed as committed to > > > > the effort? > > > > > > Yes, the working group should select a "chair" who would fill the > > > same role I do for the TC (organize meetings, push agenda, tally > > > votes on reviews, etc.) > > > > > > That would be very helpful in keeping that diverse group on track. > > > Now you just need some volunteer :) > > > > > > -- > > > Thierry Carrez (ttx) > > > > > > ___ > > > OpenStack-dev mailing list > > > OpenStack-dev@lists.openstack.org > > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Tue, 14 Oct 2014 10:29:34 -0500 Lance Bragstad wrote: > I found a couple of free times available for a weekly meeting if > people are interested: > > https://review.openstack.org/#/c/128332/2 > > Not sure if a meeting time has been hashed out already or not, and if > it has I'll change the patch accordingly. If not, we can iterate on > possible meeting times in the review if needed. This was to just get > the ball rolling if we want a weekly meeting. I proposed one review > for Thursdays at 2100 and a second patch set for 2000, UTC. That can > easily change, but those were two times that didn't conflict with the > existing meeting schedules in #openstack-meeting. So UTC 2000 is 7am Sydney, 5am Tokyo and 4am Beijing time which is pretty early in the day. I'd suggest UTC if that's not too late for others who'd like to participate. Chris > > > > On Tue, Oct 14, 2014 at 3:55 AM, Thierry Carrez > wrote: > > > Jay Pipes wrote: > > > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > > >> I guess we could also start fleshing out in the repo how we'll > > >> work in practice too (eg once the document is stable what > > >> process do we have for making changes - two +2's is probably not > > >> adequate for something like this). > > > > > > We can make it work exactly like the openstack/governance repo, > > > where ttx has the only ability to +2/+W approve a patch for > > > merging, and he tallies a majority vote from the TC members, who > > > vote -1 or +1 on a proposed patch. > > > > > > Instead of ttx, though, we can have an API working group lead > > > selected from the set of folks currently listed as committed to > > > the effort? > > > > Yes, the working group should select a "chair" who would fill the > > same role I do for the TC (organize meetings, push agenda, tally > > votes on reviews, etc.) > > > > That would be very helpful in keeping that diverse group on track. > > Now you just need some volunteer :) > > > > -- > > Thierry Carrez (ttx) > > > > ___ > > OpenStack-dev mailing list > > OpenStack-dev@lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Tue, 14 Oct 2014 09:57:01 -0400 Jay Pipes wrote: > On 10/14/2014 05:04 AM, Alex Xu wrote: > > There is one reason to think about what projects *currently* do. > > When we choice which convention we want. > > For example, the CamelCase and snake_case, if the most project use > > snake_case, then choice snake_case style > > will be the right. > > I would posit that the reason we have such inconsistencies in our > project's APIs is that we haven't taken a stand and said "this is the > way it must be". Not only have we not taken a stand, but we haven't actually told anyone what they should do in the first place. I don't think its defiance on the part of the developers of the API its just that they don't know and without any guidance just do what they think is reasonable. And a lot of the decisions (eg project vs tenant or instance vs server) are fairly arbitrary - we just need to choose one. > > There's lots of examples of inconsistencies out in the OpenStack > APIs. We can certainly use a wiki or etherpad page to document those > inconsistencies. But, eventually, this working group should produce > solid decisions that should be enforced across *future* OpenStack > APIs. And that guidance should be forthcoming in the next month or > so, not in one or two release cycles. I agree. > > I personally think proposing patches to an openstack-api repository > is the most effective way to make those proposals. Etherpads and wiki > pages are fine for dumping content, but IMO, we don't need to dump > content -- we already have plenty of it. We need to propose > guidelines for *new* APIs to follow. ok. I'm happy to go that way - I guess I disagree about us already having a lot of content. I haven't yet seen (maybe I've missed them) API guidelines suggestions from most of the openstack projects. But lets just get started :-) Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 10/14/2014 10:22 AM, Everett Toews wrote: >> I personally think proposing patches to an openstack-api repository is the >> most effective way to make those proposals. Etherpads and wiki pages are >> fine for dumping content, but IMO, we don't need to dump content -- we >> already have plenty of it. We need to propose guidelines for *new* APIs to >> follow. > +1 > > I’m all for putting a stake in the ground (in the form of docs in a repo) and > having people debate that. I think it results in a much more focused > discussion as opposed to dumping content into an etherpad/wiki page and > trying to wade through it. If people want to dump content somewhere and use > that to help inform their contributions to the repo, that’s okay too. +1 from me too. Etherpads for active discussions tend to devolve into a mess. - -- Ed Leafe -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.14 (GNU/Linux) iQIcBAEBAgAGBQJUPVQpAAoJEKMgtcocwZqL95cP/j6yt8UKflP91KRZsiXMTU/h TBb8CY3dGnwsvYJcbU5gtfvp52QAc2tnI4H8hwUGmnuaTmz0Bm3EE5gMmmB3VNw3 5a1wdoJANVQ86vRwKq8r7U5cgUIRmPDTl7OGZnS3x3H7fJR0bZa/QcFYNNU3rAqO 0HcpljDTLXU9PLKcGQ6ueeQLfZDQJGB96TZxcf+w5WUbUnLD4pMjHWnn2HR55v44 pAqHkD+swNCq061OffriG+w87+In15433QPbtNKmNQhXODCTwRI77WkVlF02p6Ca X+pi6YGMI4lshmyS4vn/7DZryrVQYxtS0lCOMHIhK0+GLdZ9TjzNAWACnSCPLuKK OYM2KEoGWJS8dHSx5WuiNcCnhZ7W+d+TM1/tgKtdGkBMmKNMSOkD5vuAywzSEJZW tUAq87SHxgINlkra9pYVzcoJGL7uLCW3655+254R4iKKX1dzZ+xEd06qawUZlHhC 8KP/eYo2ydo9fs8ABOCsh/1SdL3W9Rakw2MvG3ns79A2EVJArz+H5ngLUtm32DC6 muaPKkluS+V3JP1rDsARUY7yMXTQPbX0hr1wYdenjfqwDSSdWY1SVuPU3VFw/A7F YABxzggCbl6EvTSXPU+3uDYVbOxwOvVglG/7K2aDn3i6EIXLma6oI4EZp1wzRtj/ YS5UyN2J4wnZrjwnXr8A =lxk3 -END PGP SIGNATURE- ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/14/14, 10:22 AM, "Everett Toews" wrote: >On Oct 14, 2014, at 8:57 AM, Jay Pipes wrote: > >> I personally think proposing patches to an openstack-api repository is >>the most effective way to make those proposals. Etherpads and wiki pages >>are fine for dumping content, but IMO, we don't need to dump content -- >>we already have plenty of it. We need to propose guidelines for *new* >>APIs to follow. > >+1 > >I’m all for putting a stake in the ground (in the form of docs in a repo) >and having people debate that. I think it results in a much more focused >discussion as opposed to dumping content into an etherpad/wiki page and >trying to wade through it. If people want to dump content somewhere and >use that to help inform their contributions to the repo, that’s okay too. > >Another big benefit of putting things in a repo is provenance. Guidelines >like these can be...contentious...at times. Having a clear history of how >a guideline got into a repo is very valuable as you can link newcomers >who challenge a guideline to the history of how it got there, who >approved it, and the tradeoffs that were considered during the review >process. Of course, this is possible with etherpad/wiki too but it’s more >difficult to reconstruct the history. > >Everett Also, I don’t think the first version of the standards are going to get everything right so setting something as the starting point seems the most reasonable. Waiting entire cycles to include a new piece of the standard seems a bit impractical. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
I found a couple of free times available for a weekly meeting if people are interested: https://review.openstack.org/#/c/128332/2 Not sure if a meeting time has been hashed out already or not, and if it has I'll change the patch accordingly. If not, we can iterate on possible meeting times in the review if needed. This was to just get the ball rolling if we want a weekly meeting. I proposed one review for Thursdays at 2100 and a second patch set for 2000, UTC. That can easily change, but those were two times that didn't conflict with the existing meeting schedules in #openstack-meeting. On Tue, Oct 14, 2014 at 3:55 AM, Thierry Carrez wrote: > Jay Pipes wrote: > > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > >> I guess we could also start fleshing out in the repo how we'll work in > >> practice too (eg once the document is stable what process do we have > >> for making changes - two +2's is probably not adequate for something > >> like this). > > > > We can make it work exactly like the openstack/governance repo, where > > ttx has the only ability to +2/+W approve a patch for merging, and he > > tallies a majority vote from the TC members, who vote -1 or +1 on a > > proposed patch. > > > > Instead of ttx, though, we can have an API working group lead selected > > from the set of folks currently listed as committed to the effort? > > Yes, the working group should select a "chair" who would fill the same > role I do for the TC (organize meetings, push agenda, tally votes on > reviews, etc.) > > That would be very helpful in keeping that diverse group on track. Now > you just need some volunteer :) > > -- > Thierry Carrez (ttx) > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Oct 14, 2014, at 8:57 AM, Jay Pipes wrote: > I personally think proposing patches to an openstack-api repository is the > most effective way to make those proposals. Etherpads and wiki pages are fine > for dumping content, but IMO, we don't need to dump content -- we already > have plenty of it. We need to propose guidelines for *new* APIs to follow. +1 I’m all for putting a stake in the ground (in the form of docs in a repo) and having people debate that. I think it results in a much more focused discussion as opposed to dumping content into an etherpad/wiki page and trying to wade through it. If people want to dump content somewhere and use that to help inform their contributions to the repo, that’s okay too. Another big benefit of putting things in a repo is provenance. Guidelines like these can be...contentious...at times. Having a clear history of how a guideline got into a repo is very valuable as you can link newcomers who challenge a guideline to the history of how it got there, who approved it, and the tradeoffs that were considered during the review process. Of course, this is possible with etherpad/wiki too but it’s more difficult to reconstruct the history. Everett ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/14/2014 05:04 AM, Alex Xu wrote: There is one reason to think about what projects *currently* do. When we choice which convention we want. For example, the CamelCase and snake_case, if the most project use snake_case, then choice snake_case style will be the right. I would posit that the reason we have such inconsistencies in our project's APIs is that we haven't taken a stand and said "this is the way it must be". There's lots of examples of inconsistencies out in the OpenStack APIs. We can certainly use a wiki or etherpad page to document those inconsistencies. But, eventually, this working group should produce solid decisions that should be enforced across *future* OpenStack APIs. And that guidance should be forthcoming in the next month or so, not in one or two release cycles. I personally think proposing patches to an openstack-api repository is the most effective way to make those proposals. Etherpads and wiki pages are fine for dumping content, but IMO, we don't need to dump content -- we already have plenty of it. We need to propose guidelines for *new* APIs to follow. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/14/2014 12:52 AM, Christopher Yeoh wrote: On Mon, 13 Oct 2014 22:20:32 -0400 Jay Pipes wrote: On 10/13/2014 07:11 PM, Christopher Yeoh wrote: On Mon, 13 Oct 2014 10:52:26 -0400 Jay Pipes wrote: On 10/10/2014 02:05 AM, Christopher Yeoh wrote: I agree with what you've written on the wiki page. I think our priority needs to be to flesh out https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines so we have something to reference when reviewing specs. At the moment I see that document as something anyone should be able to document a project's API convention even if they conflict with another project for the moment. Once we've got a fair amount of content we can start as a group resolving any conflicts. Agreed that we should be fleshing out the above wiki page. How would you like us to do that? Should we have an etherpad to discuss individual topics? Having multiple people editing the wiki page offering commentary seems a bit chaotic, and I think we would do well to have the Gerrit review process in place to handle proposed guidelines and rules for APIs. See below for specifics on this... Honestly I don't think we have enough content yet to have much of a discussion. I started the wiki page https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines in the hope that people from other projects would start adding conventions that they use in their projects. I think its fine for the moment if its contradictory, we just need to gather what projects currently do (or want to do) in one place so we can start discussing any contradictions. Actually, I don't care all that much about what projects *currently* do. I want this API working group to come up with concrete guidelines and rules/examples of what APIs *should* look like. What projects currently do gives us a baseline to work from. It also should expose where we have currently have inconsistencies between projects. Sure. And whilst I don't have a problem with having some guidelines which suggest a future standard for APIs, I don't think we should be requiring any type of feature which has not yet been implemented in at least one, preferably two openstack projects and released and tested for a cycle. Eg standards should be lagging rather than leading. What about "features" in some of our APIs that are *not* preferable? For instance: API extensions. I think we've seen where API extensions leads us. And it isn't pretty. Would you suggest we document what a Nova API extension or a Neutron API extension looks like and then propose, for instance, not to ever do it again in future APIs and instead use schema discoverability? So I'd again encourage anyone interested in APIs from the various projects to just start dumping their project viewpoint in there. I went ahead and just created a repository that contained all the stuff that should be pretty much agreed-to, and a bunch of stub topic documents that can be used to propose specific ideas (and get feedback on) here: http://github.com/jaypipes/openstack-api Hopefully, you can give it a look and get a feel for why I think the code review process will be better than the wiki for controlling the deliverables produced by this team... I think it will be better in git (but we also need it in gerrit) when it comes to resolving conflicts and after we've established a decent document (eg when we have more content). I'm just looking to make it as easy as possible for anyone to add any guidelines now. Once we've actually got something to discuss then we use git/gerrit with patches proposed to resolve conflicts within the document. Of course it would be in Gerrit. I just put it up on GitHub first because I can't just add a repo into the openstack/ code namespace... :) I like the idea of a repo and using Gerrit for discussions to resolve issues. I don't think it works so well when people are wanting to dump lots of information in initially. Unless we agree to just merge anything vaguely reasonable and then resolve the conflicts later when we have a reasonable amount of content. Otherwise stuff will get lost in gerrit history comments and people's updates to the document will overwrite each other. I guess we could also start fleshing out in the repo how we'll work in practice too (eg once the document is stable what process do we have for making changes - two +2's is probably not adequate for something like this). We can make it work exactly like the openstack/governance repo, where ttx has the only ability to +2/+W approve a patch for merging, and he tallies a majority vote from the TC members, who vote -1 or +1 on a proposed patch. Instead of ttx, though, we can have an API working group lead selected from the set of folks currently listed as committed to the effort? Yep, that sounds fine, though I don't think a simple majority is sufficient for something like api standards. We either get consensus or we don't include it in the final document. Sure, those ar
Re: [openstack-dev] [api] Forming the API Working Group
On 2014年10月14日 12:52, Christopher Yeoh wrote: On Mon, 13 Oct 2014 22:20:32 -0400 Jay Pipes wrote: On 10/13/2014 07:11 PM, Christopher Yeoh wrote: On Mon, 13 Oct 2014 10:52:26 -0400 Jay Pipes wrote: On 10/10/2014 02:05 AM, Christopher Yeoh wrote: I agree with what you've written on the wiki page. I think our priority needs to be to flesh out https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines so we have something to reference when reviewing specs. At the moment I see that document as something anyone should be able to document a project's API convention even if they conflict with another project for the moment. Once we've got a fair amount of content we can start as a group resolving any conflicts. Agreed that we should be fleshing out the above wiki page. How would you like us to do that? Should we have an etherpad to discuss individual topics? Having multiple people editing the wiki page offering commentary seems a bit chaotic, and I think we would do well to have the Gerrit review process in place to handle proposed guidelines and rules for APIs. See below for specifics on this... Honestly I don't think we have enough content yet to have much of a discussion. I started the wiki page https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines in the hope that people from other projects would start adding conventions that they use in their projects. I think its fine for the moment if its contradictory, we just need to gather what projects currently do (or want to do) in one place so we can start discussing any contradictions. Actually, I don't care all that much about what projects *currently* do. I want this API working group to come up with concrete guidelines and rules/examples of what APIs *should* look like. What projects currently do gives us a baseline to work from. It also should expose where we have currently have inconsistencies between projects. And whilst I don't have a problem with having some guidelines which suggest a future standard for APIs, I don't think we should be requiring any type of feature which has not yet been implemented in at least one, preferably two openstack projects and released and tested for a cycle. Eg standards should be lagging rather than leading. There is one reason to think about what projects *currently* do. When we choice which convention we want. For example, the CamelCase and snake_case, if the most project use snake_case, then choice snake_case style will be the right. So I'd again encourage anyone interested in APIs from the various projects to just start dumping their project viewpoint in there. I went ahead and just created a repository that contained all the stuff that should be pretty much agreed-to, and a bunch of stub topic documents that can be used to propose specific ideas (and get feedback on) here: http://github.com/jaypipes/openstack-api Hopefully, you can give it a look and get a feel for why I think the code review process will be better than the wiki for controlling the deliverables produced by this team... I think it will be better in git (but we also need it in gerrit) when it comes to resolving conflicts and after we've established a decent document (eg when we have more content). I'm just looking to make it as easy as possible for anyone to add any guidelines now. Once we've actually got something to discuss then we use git/gerrit with patches proposed to resolve conflicts within the document. I like the idea of a repo and using Gerrit for discussions to resolve issues. I don't think it works so well when people are wanting to dump lots of information in initially. Unless we agree to just merge anything vaguely reasonable and then resolve the conflicts later when we have a reasonable amount of content. Otherwise stuff will get lost in gerrit history comments and people's updates to the document will overwrite each other. I guess we could also start fleshing out in the repo how we'll work in practice too (eg once the document is stable what process do we have for making changes - two +2's is probably not adequate for something like this). We can make it work exactly like the openstack/governance repo, where ttx has the only ability to +2/+W approve a patch for merging, and he tallies a majority vote from the TC members, who vote -1 or +1 on a proposed patch. Instead of ttx, though, we can have an API working group lead selected from the set of folks currently listed as committed to the effort? Yep, that sounds fine, though I don't think a simple majority is sufficient for something like api standards. We either get consensus or we don't include it in the final document. Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.or
Re: [openstack-dev] [api] Forming the API Working Group
Jay Pipes wrote: > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: >> I guess we could also start fleshing out in the repo how we'll work in >> practice too (eg once the document is stable what process do we have >> for making changes - two +2's is probably not adequate for something >> like this). > > We can make it work exactly like the openstack/governance repo, where > ttx has the only ability to +2/+W approve a patch for merging, and he > tallies a majority vote from the TC members, who vote -1 or +1 on a > proposed patch. > > Instead of ttx, though, we can have an API working group lead selected > from the set of folks currently listed as committed to the effort? Yes, the working group should select a "chair" who would fill the same role I do for the TC (organize meetings, push agenda, tally votes on reviews, etc.) That would be very helpful in keeping that diverse group on track. Now you just need some volunteer :) -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Tue, 14 Oct 2014 05:27:21 +0200 "Ken'ichi Ohmichi" wrote: > 2014-10-13 16:52 GMT+02:00 Jay Pipes : > > On 10/10/2014 02:05 AM, Christopher Yeoh wrote: > >> > >> I agree with what you've written on the wiki page. I think our > >> priority needs to be to flesh out > >> https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines > >> so we have something to reference when reviewing specs. At the > >> moment I see that document as something anyone should be able to > >> document a project's API convention even if they conflict with > >> another project for the moment. Once we've got a fair amount of > >> content we can start as a group resolving > >> any conflicts. > > > > > > Agreed that we should be fleshing out the above wiki page. How > > would you like us to do that? Should we have an etherpad to discuss > > individual topics? Having multiple people editing the wiki page > > offering commentary seems a bit chaotic, and I think we would do > > well to have the Gerrit review process in place to handle proposed > > guidelines and rules for APIs. See below for specifics on this... > > > >> Speaking of the wiki page, I wrote it very matter-of-factly. > >> As if this is the way things are. They’re not. The wiki page is > >> just a starting point. If something was missed, add it. If > >> something can be improved, improve it. Let’s try to keep it simple > >> though. > >> > >> One problem with API WG members reviewing spec proposals that > >> affect the API is finding the specs in the first place across many > >> different projects repositories. > > > > > > I've said for a while now that I would love to have separate > > repositories -- ala the Keystone API in the openstack/identity-api > > repository -- that contains specifications for APIs in a single > > format (APIBlueprint was suggested at one point, but Swagger 2.0 > > seems to me to have more upside). > > > > I also think it would be ideal to have an openstack/openstack-api > > repo that would house guidelines and rules that this working group > > came up with, along with examples of appropriate usage. This repo > > would function very similar to the openstack/governance [1] repo > > that the TC uses to flesh out proposals on community, release > > management, and governance changes. > > > > If people are OK with this idea, I will go ahead and create the > > repo and add the wiki page content as the initial commit, then > > everyone can simply submit patches to the document(s) using the > > normal Gerrit process, and we can iterate on these things using the > > same tools as other repositories. > > Thanks Jay, > > I much prefer this idea. > I concerned how to handle API rule conflicts if using a wiki page. > eg: Someone prefer CamelCase names as attributes but the other does > snake_case. If using gerrit, we can propose favorite rules as each > commit and we can discuss them on it. That would be nice to build a > consensus for the rules. So for now I'd suggest just adding both - CamelCase and snake_case as possible guidelines. Once we have all these (possibly conflicting) ideas in the document then we move it to git/gerrit and propose patches to resolve any conflicts or remove bits that people don't like. Eg. I'm suggesting we work from a large document where everyone gets to throw their opinions in and cut it down rather than start from nothing and try to build it up patch by patch. I think its a better way for ensuring people see other people's ideas and where they conflict with other people's. Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Mon, 13 Oct 2014 22:20:32 -0400 Jay Pipes wrote: > On 10/13/2014 07:11 PM, Christopher Yeoh wrote: > > On Mon, 13 Oct 2014 10:52:26 -0400 > > Jay Pipes wrote: > > > >> On 10/10/2014 02:05 AM, Christopher Yeoh wrote: > >>> I agree with what you've written on the wiki page. I think our > >>> priority needs to be to flesh out > >>> https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines > >>> so we have something to reference when reviewing specs. At the > >>> moment I see that document as something anyone should be able to > >>> document a project's API convention even if they conflict with > >>> another project for the moment. Once we've got a fair amount of > >>> content we can start as a group resolving > >>> any conflicts. > >> > >> Agreed that we should be fleshing out the above wiki page. How > >> would you like us to do that? Should we have an etherpad to discuss > >> individual topics? Having multiple people editing the wiki page > >> offering commentary seems a bit chaotic, and I think we would do > >> well to have the Gerrit review process in place to handle proposed > >> guidelines and rules for APIs. See below for specifics on this... > > > > Honestly I don't think we have enough content yet to have much of a > > discussion. I started the wiki page > > > > https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines > > > > in the hope that people from other projects would start adding > > conventions that they use in their projects. I think its fine for > > the moment if its contradictory, we just need to gather what > > projects currently do (or want to do) in one place so we can start > > discussing any contradictions. > > Actually, I don't care all that much about what projects *currently* > do. I want this API working group to come up with concrete guidelines > and rules/examples of what APIs *should* look like. What projects currently do gives us a baseline to work from. It also should expose where we have currently have inconsistencies between projects. And whilst I don't have a problem with having some guidelines which suggest a future standard for APIs, I don't think we should be requiring any type of feature which has not yet been implemented in at least one, preferably two openstack projects and released and tested for a cycle. Eg standards should be lagging rather than leading. > > So I'd again encourage anyone interested in APIs from the various > > projects to just start dumping their project viewpoint in there. > > I went ahead and just created a repository that contained all the > stuff that should be pretty much agreed-to, and a bunch of stub topic > documents that can be used to propose specific ideas (and get > feedback on) here: > > http://github.com/jaypipes/openstack-api > > Hopefully, you can give it a look and get a feel for why I think the > code review process will be better than the wiki for controlling the > deliverables produced by this team... I think it will be better in git (but we also need it in gerrit) when it comes to resolving conflicts and after we've established a decent document (eg when we have more content). I'm just looking to make it as easy as possible for anyone to add any guidelines now. Once we've actually got something to discuss then we use git/gerrit with patches proposed to resolve conflicts within the document. > > > I like the idea of a repo and using Gerrit for discussions to > > resolve issues. I don't think it works so well when people are > > wanting to dump lots of information in initially. Unless we agree > > to just merge anything vaguely reasonable and then resolve the > > conflicts later when we have a reasonable amount of content. > > Otherwise stuff will get lost in gerrit history comments and > > people's updates to the document will overwrite each other. > > > > I guess we could also start fleshing out in the repo how we'll work > > in practice too (eg once the document is stable what process do we > > have for making changes - two +2's is probably not adequate for > > something like this). > > We can make it work exactly like the openstack/governance repo, where > ttx has the only ability to +2/+W approve a patch for merging, and he > tallies a majority vote from the TC members, who vote -1 or +1 on a > proposed patch. > > Instead of ttx, though, we can have an API working group lead > selected from the set of folks currently listed as committed to the > effort? Yep, that sounds fine, though I don't think a simple majority is sufficient for something like api standards. We either get consensus or we don't include it in the final document. Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
2014-10-13 16:52 GMT+02:00 Jay Pipes : > On 10/10/2014 02:05 AM, Christopher Yeoh wrote: >> >> I agree with what you've written on the wiki page. I think our priority >> needs to be to flesh out >> https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines >> so we have something to reference when reviewing specs. At the moment I >> see that document as something anyone should be able to document a >> project's API convention even if they conflict with another project for >> the moment. Once we've got a fair amount of content we can start as a >> group resolving >> any conflicts. > > > Agreed that we should be fleshing out the above wiki page. How would you > like us to do that? Should we have an etherpad to discuss individual topics? > Having multiple people editing the wiki page offering commentary seems a bit > chaotic, and I think we would do well to have the Gerrit review process in > place to handle proposed guidelines and rules for APIs. See below for > specifics on this... > >> Speaking of the wiki page, I wrote it very matter-of-factly. As if >> this is the way things are. They’re not. The wiki page is just a >> starting point. If something was missed, add it. If something can be >> improved, improve it. Let’s try to keep it simple though. >> >> One problem with API WG members reviewing spec proposals that affect the >> API is finding the specs in the first place across many different >> projects repositories. > > > I've said for a while now that I would love to have separate repositories -- > ala the Keystone API in the openstack/identity-api repository -- that > contains specifications for APIs in a single format (APIBlueprint was > suggested at one point, but Swagger 2.0 seems to me to have more upside). > > I also think it would be ideal to have an openstack/openstack-api repo that > would house guidelines and rules that this working group came up with, along > with examples of appropriate usage. This repo would function very similar to > the openstack/governance [1] repo that the TC uses to flesh out proposals on > community, release management, and governance changes. > > If people are OK with this idea, I will go ahead and create the repo and add > the wiki page content as the initial commit, then everyone can simply submit > patches to the document(s) using the normal Gerrit process, and we can > iterate on these things using the same tools as other repositories. Thanks Jay, I much prefer this idea. I concerned how to handle API rule conflicts if using a wiki page. eg: Someone prefer CamelCase names as attributes but the other does snake_case. If using gerrit, we can propose favorite rules as each commit and we can discuss them on it. That would be nice to build a consensus for the rules. Thanks Ken ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/13/2014 07:11 PM, Christopher Yeoh wrote: On Mon, 13 Oct 2014 10:52:26 -0400 Jay Pipes wrote: On 10/10/2014 02:05 AM, Christopher Yeoh wrote: I agree with what you've written on the wiki page. I think our priority needs to be to flesh out https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines so we have something to reference when reviewing specs. At the moment I see that document as something anyone should be able to document a project's API convention even if they conflict with another project for the moment. Once we've got a fair amount of content we can start as a group resolving any conflicts. Agreed that we should be fleshing out the above wiki page. How would you like us to do that? Should we have an etherpad to discuss individual topics? Having multiple people editing the wiki page offering commentary seems a bit chaotic, and I think we would do well to have the Gerrit review process in place to handle proposed guidelines and rules for APIs. See below for specifics on this... Honestly I don't think we have enough content yet to have much of a discussion. I started the wiki page https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines in the hope that people from other projects would start adding conventions that they use in their projects. I think its fine for the moment if its contradictory, we just need to gather what projects currently do (or want to do) in one place so we can start discussing any contradictions. Actually, I don't care all that much about what projects *currently* do. I want this API working group to come up with concrete guidelines and rules/examples of what APIs *should* look like. So I'd again encourage anyone interested in APIs from the various projects to just start dumping their project viewpoint in there. I went ahead and just created a repository that contained all the stuff that should be pretty much agreed-to, and a bunch of stub topic documents that can be used to propose specific ideas (and get feedback on) here: http://github.com/jaypipes/openstack-api Hopefully, you can give it a look and get a feel for why I think the code review process will be better than the wiki for controlling the deliverables produced by this team... I like the idea of a repo and using Gerrit for discussions to resolve issues. I don't think it works so well when people are wanting to dump lots of information in initially. Unless we agree to just merge anything vaguely reasonable and then resolve the conflicts later when we have a reasonable amount of content. Otherwise stuff will get lost in gerrit history comments and people's updates to the document will overwrite each other. I guess we could also start fleshing out in the repo how we'll work in practice too (eg once the document is stable what process do we have for making changes - two +2's is probably not adequate for something like this). We can make it work exactly like the openstack/governance repo, where ttx has the only ability to +2/+W approve a patch for merging, and he tallies a majority vote from the TC members, who vote -1 or +1 on a proposed patch. Instead of ttx, though, we can have an API working group lead selected from the set of folks currently listed as committed to the effort? Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On Mon, 13 Oct 2014 10:52:26 -0400 Jay Pipes wrote: > On 10/10/2014 02:05 AM, Christopher Yeoh wrote: > > I agree with what you've written on the wiki page. I think our > > priority needs to be to flesh out > > https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines > > so we have something to reference when reviewing specs. At the > > moment I see that document as something anyone should be able to > > document a project's API convention even if they conflict with > > another project for the moment. Once we've got a fair amount of > > content we can start as a group resolving > > any conflicts. > > Agreed that we should be fleshing out the above wiki page. How would > you like us to do that? Should we have an etherpad to discuss > individual topics? Having multiple people editing the wiki page > offering commentary seems a bit chaotic, and I think we would do well > to have the Gerrit review process in place to handle proposed > guidelines and rules for APIs. See below for specifics on this... Honestly I don't think we have enough content yet to have much of a discussion. I started the wiki page https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines in the hope that people from other projects would start adding conventions that they use in their projects. I think its fine for the moment if its contradictory, we just need to gather what projects currently do (or want to do) in one place so we can start discussing any contradictions. So I'd again encourage anyone interested in APIs from the various projects to just start dumping their project viewpoint in there. > > Speaking of the wiki page, I wrote it very matter-of-factly. As > > if this is the way things are. They’re not. The wiki page is just a > > starting point. If something was missed, add it. If something > > can be improved, improve it. Let’s try to keep it simple though. > > > > One problem with API WG members reviewing spec proposals that > > affect the API is finding the specs in the first place across many > > different projects repositories. > > I've said for a while now that I would love to have separate > repositories -- ala the Keystone API in the openstack/identity-api > repository -- that contains specifications for APIs in a single > format (APIBlueprint was suggested at one point, but Swagger 2.0 > seems to me to have more upside). > > I also think it would be ideal to have an openstack/openstack-api > repo that would house guidelines and rules that this working group > came up with, along with examples of appropriate usage. This repo > would function very similar to the openstack/governance [1] repo that > the TC uses to flesh out proposals on community, release management, > and governance changes. > > If people are OK with this idea, I will go ahead and create the repo > and add the wiki page content as the initial commit, then everyone > can simply submit patches to the document(s) using the normal Gerrit > process, and we can iterate on these things using the same tools as > other repositories. I like the idea of a repo and using Gerrit for discussions to resolve issues. I don't think it works so well when people are wanting to dump lots of information in initially. Unless we agree to just merge anything vaguely reasonable and then resolve the conflicts later when we have a reasonable amount of content. Otherwise stuff will get lost in gerrit history comments and people's updates to the document will overwrite each other. I guess we could also start fleshing out in the repo how we'll work in practice too (eg once the document is stable what process do we have for making changes - two +2's is probably not adequate for something like this). Regards, Chris > > Best, > -jay > > [1] > https://review.openstack.org/#/q/status:open+project:openstack/governance,n,z > > > I invite everyone who chimed in on the original thread [1] that > > kicked this off to add themselves as a member committed to > > making the OpenStack APIs better. I’ve Cc’d everyone who asked to > > be kept in the loop. > > > > I already see some cross project summit topics [2] on APIs. But > > frankly, with the number of people committed to this topic, I’d > > expect there to be more. I encourage everyone to submit more API > > related sessions with better descriptions and goals about what > > you want to achieve in those sessions. > > > > Yea if there is enough content in the API guidelines then perhaps > > some time can be spent on working on resolving any conflicts in the > > document so projects know what direction to head in. > > > > Regards, > > > > Chris > > > > > > ___ > > OpenStack-dev mailing list > > OpenStack-dev@lists.openstack.org > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.
Re: [openstack-dev] [api] Forming the API Working Group
Zhipeng Huang wrote: > THX for the link ! So we will have the workshop on Nov 3th at Meridien > Etoile Hotel? The workshops happen on the 4th (Tuesday). -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/13/2014 11:10 AM, Russell Bryant wrote: On 10/10/2014 12:09 PM, Jay Pipes wrote: Thanks for getting this going, Everett! Comments inline... On 10/08/2014 07:05 PM, Everett Toews wrote: https://wiki.openstack.org/wiki/API_Working_Group This is the start of the API Working Group (API WG). yay! :) To avoid bike shedding over the name of the working group, I decided to title the wiki page API Working Group. Simple, to the point, and avoids loaded terms like standards, best practices, guidelines, conventions, etc. Yup, ++ The point isn’t what we name it. The point is what action we take about it. I propose the deliverables in the API WG wiki page. Speaking of the wiki page, I wrote it very matter-of-factly. As if this is the way things are. They’re not. The wiki page is just a starting point. If something was missed, add it. If something can be improved, improve it. Let’s try to keep it simple though. The wiki content looks fine, with the exception that I really do feel the working group needs to have some ability to review and enforce consistency within proposed REST APIs. The wording right now is: "The API WG is focused on creating guidelines for the APIs" which of course is fine, but I think that the Technical Committee should essentially grant the working group the power to enforce guidelines and consistency for proposed new REST APIs -- whether it's a new REST API version in an existing project or a REST APi for a newly-proposed OpenStack server project. I think that's a great goal. I'd like to see the group earn this level of influence based on its own merit rather than have the TC just grant it up front. I'd say let's give the group a cycle to build up, generate guidelines, and participate in API design reviews. I'd rather see it as the TC making something official that was effectively already happening in practice. Sure, totally fair point. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/10/2014 12:09 PM, Jay Pipes wrote: > Thanks for getting this going, Everett! Comments inline... > > On 10/08/2014 07:05 PM, Everett Toews wrote: >> https://wiki.openstack.org/wiki/API_Working_Group >> >> This is the start of the API Working Group (API WG). > > yay! :) > >> To avoid bike shedding over the name of the working group, I decided >> to title the wiki page API Working Group. Simple, to the point, and >> avoids loaded terms like standards, best practices, guidelines, >> conventions, etc. > > Yup, ++ > >> The point isn’t what we name it. The point is what action we take >> about it. I propose the deliverables in the API WG wiki page. >> >> Speaking of the wiki page, I wrote it very matter-of-factly. As if >> this is the way things are. They’re not. The wiki page is just a >> starting point. If something was missed, add it. If something can be >> improved, improve it. Let’s try to keep it simple though. > > The wiki content looks fine, with the exception that I really do feel > the working group needs to have some ability to review and enforce > consistency within proposed REST APIs. The wording right now is: > > "The API WG is focused on creating guidelines for the APIs" > > which of course is fine, but I think that the Technical Committee should > essentially grant the working group the power to enforce guidelines and > consistency for proposed new REST APIs -- whether it's a new REST API > version in an existing project or a REST APi for a newly-proposed > OpenStack server project. I think that's a great goal. I'd like to see the group earn this level of influence based on its own merit rather than have the TC just grant it up front. I'd say let's give the group a cycle to build up, generate guidelines, and participate in API design reviews. I'd rather see it as the TC making something official that was effectively already happening in practice. -- Russell Bryant ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
On 10/10/2014 02:05 AM, Christopher Yeoh wrote: I agree with what you've written on the wiki page. I think our priority needs to be to flesh out https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines so we have something to reference when reviewing specs. At the moment I see that document as something anyone should be able to document a project's API convention even if they conflict with another project for the moment. Once we've got a fair amount of content we can start as a group resolving any conflicts. Agreed that we should be fleshing out the above wiki page. How would you like us to do that? Should we have an etherpad to discuss individual topics? Having multiple people editing the wiki page offering commentary seems a bit chaotic, and I think we would do well to have the Gerrit review process in place to handle proposed guidelines and rules for APIs. See below for specifics on this... Speaking of the wiki page, I wrote it very matter-of-factly. As if this is the way things are. They’re not. The wiki page is just a starting point. If something was missed, add it. If something can be improved, improve it. Let’s try to keep it simple though. One problem with API WG members reviewing spec proposals that affect the API is finding the specs in the first place across many different projects repositories. I've said for a while now that I would love to have separate repositories -- ala the Keystone API in the openstack/identity-api repository -- that contains specifications for APIs in a single format (APIBlueprint was suggested at one point, but Swagger 2.0 seems to me to have more upside). I also think it would be ideal to have an openstack/openstack-api repo that would house guidelines and rules that this working group came up with, along with examples of appropriate usage. This repo would function very similar to the openstack/governance [1] repo that the TC uses to flesh out proposals on community, release management, and governance changes. If people are OK with this idea, I will go ahead and create the repo and add the wiki page content as the initial commit, then everyone can simply submit patches to the document(s) using the normal Gerrit process, and we can iterate on these things using the same tools as other repositories. Best, -jay [1] https://review.openstack.org/#/q/status:open+project:openstack/governance,n,z I invite everyone who chimed in on the original thread [1] that kicked this off to add themselves as a member committed to making the OpenStack APIs better. I’ve Cc’d everyone who asked to be kept in the loop. I already see some cross project summit topics [2] on APIs. But frankly, with the number of people committed to this topic, I’d expect there to be more. I encourage everyone to submit more API related sessions with better descriptions and goals about what you want to achieve in those sessions. Yea if there is enough content in the API guidelines then perhaps some time can be spent on working on resolving any conflicts in the document so projects know what direction to head in. Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
Hi Thierry, THX for the link ! So we will have the workshop on Nov 3th at Meridien Etoile Hotel? On Mon, Oct 13, 2014 at 8:40 PM, Thierry Carrez wrote: > Zhipeng Huang wrote: > > HI all, will we have a discussion on this issun at Paris Summit? > > I expect the API WG to propose API discussions within the "Cross-project > workshops" track and get space granted to them. > > https://etherpad.openstack.org/p/kilo-crossproject-summit-topics > > Cheers, > > -- > Thierry Carrez (ttx) > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > -- Zhipeng Huang Research Assistant Mobile Ad-Hoc Network Lab, Calit2 University of California, Irvine Email: zhipe...@uci.edu Office: Calit2 Building Room 2402 OpenStack, OpenDaylight, OpenCompute affcienado ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
Zhipeng Huang wrote: > HI all, will we have a discussion on this issun at Paris Summit? I expect the API WG to propose API discussions within the "Cross-project workshops" track and get space granted to them. https://etherpad.openstack.org/p/kilo-crossproject-summit-topics Cheers, -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
HI all, will we have a discussion on this issun at Paris Summit? On Sun, Oct 12, 2014 at 8:32 AM, Preston L. Bannister wrote: > Tricky. First, I am new to OpenStack, and as such tend to want to shut-up > and listen. > > Second, I have done APIs for distributed systems for over 30 years. Yes, I > got in very early. As such I am guilty of or saw lots of bad examples. Also > I found patterns that worked very well. > > That said, the approach to APIs and versioning in OpenStack ... does not > make sense, to me. Seems a mess. Maybe I am wrong. Or not. > > The notion of a group that offers living advice to the various OpenStack > projects on APIs is - I think - a good notion. Written guidelines are good, > to a point, but only that. Interpreting static documents has limits. > > My current impression is the folk offering APIs need help. So if this > offering evaluates in the end as help, this is a good idea. :) > > > > On Fri, Oct 10, 2014 at 9:09 AM, Jay Pipes wrote: > >> Thanks for getting this going, Everett! Comments inline... >> >> On 10/08/2014 07:05 PM, Everett Toews wrote: >> >>> https://wiki.openstack.org/wiki/API_Working_Group >>> >>> This is the start of the API Working Group (API WG). >>> >> >> yay! :) >> >> To avoid bike shedding over the name of the working group, I decided >>> to title the wiki page API Working Group. Simple, to the point, and >>> avoids loaded terms like standards, best practices, guidelines, >>> conventions, etc. >>> >> >> Yup, ++ >> >> The point isn’t what we name it. The point is what action we take >>> about it. I propose the deliverables in the API WG wiki page. >>> >>> Speaking of the wiki page, I wrote it very matter-of-factly. As if >>> this is the way things are. They’re not. The wiki page is just a >>> starting point. If something was missed, add it. If something can be >>> improved, improve it. Let’s try to keep it simple though. >>> >> >> The wiki content looks fine, with the exception that I really do feel the >> working group needs to have some ability to review and enforce consistency >> within proposed REST APIs. The wording right now is: >> >> "The API WG is focused on creating guidelines for the APIs" >> >> which of course is fine, but I think that the Technical Committee should >> essentially grant the working group the power to enforce guidelines and >> consistency for proposed new REST APIs -- whether it's a new REST API >> version in an existing project or a REST APi for a newly-proposed OpenStack >> server project. >> >> I invite everyone who chimed in on the original thread [1] that >>> kicked this off to add themselves as a member committed to making the >>> OpenStack APIs better. I’ve Cc’d everyone who asked to be kept in the >>> loop. >>> >>> I already see some cross project summit topics [2] on APIs. But >>> frankly, with the number of people committed to this topic, I’d >>> expect there to be more. I encourage everyone to submit more API >>> related sessions with better descriptions and goals about what you >>> want to achieve in those sessions. >>> >> >> Will do. >> >> Best, >> -jay >> >> >> Regards, Everett >>> >>> [1] >>> http://lists.openstack.org/pipermail/openstack-dev/2014- >>> September/046850.html >>> [2] https://etherpad.openstack.org/p/kilo-crossproject-summit-topics >>> >> >> ___ >> OpenStack-dev mailing list >> OpenStack-dev@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > -- Zhipeng Huang Research Assistant Mobile Ad-Hoc Network Lab, Calit2 University of California, Irvine Email: zhipe...@uci.edu Office: Calit2 Building Room 2402 OpenStack, OpenDaylight, OpenCompute affcienado ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
Tricky. First, I am new to OpenStack, and as such tend to want to shut-up and listen. Second, I have done APIs for distributed systems for over 30 years. Yes, I got in very early. As such I am guilty of or saw lots of bad examples. Also I found patterns that worked very well. That said, the approach to APIs and versioning in OpenStack ... does not make sense, to me. Seems a mess. Maybe I am wrong. Or not. The notion of a group that offers living advice to the various OpenStack projects on APIs is - I think - a good notion. Written guidelines are good, to a point, but only that. Interpreting static documents has limits. My current impression is the folk offering APIs need help. So if this offering evaluates in the end as help, this is a good idea. :) On Fri, Oct 10, 2014 at 9:09 AM, Jay Pipes wrote: > Thanks for getting this going, Everett! Comments inline... > > On 10/08/2014 07:05 PM, Everett Toews wrote: > >> https://wiki.openstack.org/wiki/API_Working_Group >> >> This is the start of the API Working Group (API WG). >> > > yay! :) > > To avoid bike shedding over the name of the working group, I decided >> to title the wiki page API Working Group. Simple, to the point, and >> avoids loaded terms like standards, best practices, guidelines, >> conventions, etc. >> > > Yup, ++ > > The point isn’t what we name it. The point is what action we take >> about it. I propose the deliverables in the API WG wiki page. >> >> Speaking of the wiki page, I wrote it very matter-of-factly. As if >> this is the way things are. They’re not. The wiki page is just a >> starting point. If something was missed, add it. If something can be >> improved, improve it. Let’s try to keep it simple though. >> > > The wiki content looks fine, with the exception that I really do feel the > working group needs to have some ability to review and enforce consistency > within proposed REST APIs. The wording right now is: > > "The API WG is focused on creating guidelines for the APIs" > > which of course is fine, but I think that the Technical Committee should > essentially grant the working group the power to enforce guidelines and > consistency for proposed new REST APIs -- whether it's a new REST API > version in an existing project or a REST APi for a newly-proposed OpenStack > server project. > > I invite everyone who chimed in on the original thread [1] that >> kicked this off to add themselves as a member committed to making the >> OpenStack APIs better. I’ve Cc’d everyone who asked to be kept in the >> loop. >> >> I already see some cross project summit topics [2] on APIs. But >> frankly, with the number of people committed to this topic, I’d >> expect there to be more. I encourage everyone to submit more API >> related sessions with better descriptions and goals about what you >> want to achieve in those sessions. >> > > Will do. > > Best, > -jay > > > Regards, Everett >> >> [1] >> http://lists.openstack.org/pipermail/openstack-dev/2014- >> September/046850.html >> [2] https://etherpad.openstack.org/p/kilo-crossproject-summit-topics >> > > ___ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
Thanks for getting this going, Everett! Comments inline... On 10/08/2014 07:05 PM, Everett Toews wrote: https://wiki.openstack.org/wiki/API_Working_Group This is the start of the API Working Group (API WG). yay! :) To avoid bike shedding over the name of the working group, I decided to title the wiki page API Working Group. Simple, to the point, and avoids loaded terms like standards, best practices, guidelines, conventions, etc. Yup, ++ The point isn’t what we name it. The point is what action we take about it. I propose the deliverables in the API WG wiki page. Speaking of the wiki page, I wrote it very matter-of-factly. As if this is the way things are. They’re not. The wiki page is just a starting point. If something was missed, add it. If something can be improved, improve it. Let’s try to keep it simple though. The wiki content looks fine, with the exception that I really do feel the working group needs to have some ability to review and enforce consistency within proposed REST APIs. The wording right now is: "The API WG is focused on creating guidelines for the APIs" which of course is fine, but I think that the Technical Committee should essentially grant the working group the power to enforce guidelines and consistency for proposed new REST APIs -- whether it's a new REST API version in an existing project or a REST APi for a newly-proposed OpenStack server project. I invite everyone who chimed in on the original thread [1] that kicked this off to add themselves as a member committed to making the OpenStack APIs better. I’ve Cc’d everyone who asked to be kept in the loop. I already see some cross project summit topics [2] on APIs. But frankly, with the number of people committed to this topic, I’d expect there to be more. I encourage everyone to submit more API related sessions with better descriptions and goals about what you want to achieve in those sessions. Will do. Best, -jay Regards, Everett [1] http://lists.openstack.org/pipermail/openstack-dev/2014-September/046850.html [2] https://etherpad.openstack.org/p/kilo-crossproject-summit-topics ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Forming the API Working Group
Hi Everett, Great to see things moving with the API Working Group! On Thu, Oct 9, 2014 at 9:35 AM, Everett Toews wrote: > https://wiki.openstack.org/wiki/API_Working_Group > > This is the start of the API Working Group (API WG). > > To avoid bike shedding over the name of the working group, I decided to > title the wiki page API Working Group. Simple, to the point, and avoids > loaded terms like standards, best practices, guidelines, conventions, etc. > > The point isn’t what we name it. The point is what action we take about > it. I propose the deliverables in the API WG wiki page. > > I agree with what you've written on the wiki page. I think our priority needs to be to flesh out https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines so we have something to reference when reviewing specs. At the moment I see that document as something anyone should be able to document a project's API convention even if they conflict with another project for the moment. Once we've got a fair amount of content we can start as a group resolving any conflicts. > Speaking of the wiki page, I wrote it very matter-of-factly. As if this is > the way things are. They’re not. The wiki page is just a starting point. If > something was missed, add it. If something can be improved, improve it. > Let’s try to keep it simple though. > > One problem with API WG members reviewing spec proposals that affect the API is finding the specs in the first place across many different projects repositories. > I invite everyone who chimed in on the original thread [1] that kicked > this off to add themselves as a member committed to making the OpenStack > APIs better. I’ve Cc’d everyone who asked to be kept in the loop. > > I already see some cross project summit topics [2] on APIs. But frankly, > with the number of people committed to this topic, I’d expect there to be > more. I encourage everyone to submit more API related sessions with better > descriptions and goals about what you want to achieve in those sessions. > > Yea if there is enough content in the API guidelines then perhaps some time can be spent on working on resolving any conflicts in the document so projects know what direction to head in. Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [api] Forming the API Working Group
https://wiki.openstack.org/wiki/API_Working_Group This is the start of the API Working Group (API WG). To avoid bike shedding over the name of the working group, I decided to title the wiki page API Working Group. Simple, to the point, and avoids loaded terms like standards, best practices, guidelines, conventions, etc. The point isn’t what we name it. The point is what action we take about it. I propose the deliverables in the API WG wiki page. Speaking of the wiki page, I wrote it very matter-of-factly. As if this is the way things are. They’re not. The wiki page is just a starting point. If something was missed, add it. If something can be improved, improve it. Let’s try to keep it simple though. I invite everyone who chimed in on the original thread [1] that kicked this off to add themselves as a member committed to making the OpenStack APIs better. I’ve Cc’d everyone who asked to be kept in the loop. I already see some cross project summit topics [2] on APIs. But frankly, with the number of people committed to this topic, I’d expect there to be more. I encourage everyone to submit more API related sessions with better descriptions and goals about what you want to achieve in those sessions. Regards, Everett [1] http://lists.openstack.org/pipermail/openstack-dev/2014-September/046850.html [2] https://etherpad.openstack.org/p/kilo-crossproject-summit-topics ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
