Re: [openstack-dev] [api] Forming the API Working Group

2014-10-14 Thread Thierry Carrez
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

2014-10-14 Thread Alex Xu

On 2014年10月14日 12:52, Christopher Yeoh wrote:

On Mon, 13 Oct 2014 22:20:32 -0400
Jay Pipes jaypi...@gmail.com wrote:


On 10/13/2014 07:11 PM, Christopher Yeoh wrote:

On Mon, 13 Oct 2014 10:52:26 -0400
Jay Pipes jaypi...@gmail.com 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

Re: [openstack-dev] [api] Forming the API Working Group

2014-10-14 Thread Jay Pipes

On 10/14/2014 12:52 AM, Christopher Yeoh wrote:

On Mon, 13 Oct 2014 22:20:32 -0400
Jay Pipes jaypi...@gmail.com wrote:


On 10/13/2014 07:11 PM, Christopher Yeoh wrote:

On Mon, 13 Oct 2014 10:52:26 -0400
Jay Pipes jaypi...@gmail.com 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 

Re: [openstack-dev] [api] Forming the API Working Group

2014-10-14 Thread Everett Toews
On Oct 14, 2014, at 8:57 AM, Jay Pipes jaypi...@gmail.com 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

2014-10-14 Thread Lance Bragstad
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 thie...@openstack.org
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

2014-10-14 Thread Ian Cordasco


On 10/14/14, 10:22 AM, Everett Toews everett.to...@rackspace.com wrote:

On Oct 14, 2014, at 8:57 AM, Jay Pipes jaypi...@gmail.com 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

2014-10-14 Thread Ed Leafe
-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

2014-10-14 Thread Christopher Yeoh
On Tue, 14 Oct 2014 09:57:01 -0400
Jay Pipes jaypi...@gmail.com 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

2014-10-14 Thread Christopher Yeoh
On Tue, 14 Oct 2014 10:29:34 -0500
Lance Bragstad lbrags...@gmail.com 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
 thie...@openstack.org 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

2014-10-14 Thread Lance Bragstad
On Tue, Oct 14, 2014 at 4:29 PM, Christopher Yeoh cbky...@gmail.com wrote:

 On Tue, 14 Oct 2014 10:29:34 -0500
 Lance Bragstad lbrags...@gmail.com 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
  thie...@openstack.org 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

2014-10-14 Thread Christopher Yeoh
On Tue, 14 Oct 2014 09:45:44 -0400
Jay Pipes jaypi...@gmail.com wrote:

 On 10/14/2014 12:52 AM, Christopher Yeoh wrote:
  On Mon, 13 Oct 2014 22:20:32 -0400
  Jay Pipes jaypi...@gmail.com 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

2014-10-14 Thread Doug Hellmann

On Oct 14, 2014, at 6:00 PM, Lance Bragstad lbrags...@gmail.com wrote:

 
 
 On Tue, Oct 14, 2014 at 4:29 PM, Christopher Yeoh cbky...@gmail.com wrote:
 On Tue, 14 Oct 2014 10:29:34 -0500
 Lance Bragstad lbrags...@gmail.com 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
  thie...@openstack.org 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

2014-10-14 Thread Zhipeng Huang
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 d...@doughellmann.com
wrote:


 On Oct 14, 2014, at 6:00 PM, Lance Bragstad lbrags...@gmail.com wrote:



 On Tue, Oct 14, 2014 at 4:29 PM, Christopher Yeoh cbky...@gmail.com
 wrote:

 On Tue, 14 Oct 2014 10:29:34 -0500
 Lance Bragstad lbrags...@gmail.com 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
  thie...@openstack.org 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

2014-10-14 Thread Alex Xu

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

2014-10-14 Thread GHANSHYAM MANN
On Wed, Oct 15, 2014 at 7:44 AM, Christopher Yeoh cbky...@gmail.com wrote:

 On Tue, 14 Oct 2014 09:45:44 -0400
 Jay Pipes jaypi...@gmail.com wrote:

  On 10/14/2014 12:52 AM, Christopher Yeoh wrote:
   On Mon, 13 Oct 2014 22:20:32 -0400
   Jay Pipes jaypi...@gmail.com 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

2014-10-13 Thread Thierry Carrez
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

2014-10-13 Thread 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.


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

2014-10-13 Thread Russell Bryant
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

2014-10-13 Thread Jay Pipes

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

2014-10-13 Thread Thierry Carrez
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

2014-10-13 Thread Christopher Yeoh
On Mon, 13 Oct 2014 10:52:26 -0400
Jay Pipes jaypi...@gmail.com 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.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


___

Re: [openstack-dev] [api] Forming the API Working Group

2014-10-13 Thread Jay Pipes

On 10/13/2014 07:11 PM, Christopher Yeoh wrote:

On Mon, 13 Oct 2014 10:52:26 -0400
Jay Pipes jaypi...@gmail.com 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

2014-10-13 Thread Ken'ichi Ohmichi
2014-10-13 16:52 GMT+02:00 Jay Pipes jaypi...@gmail.com:
 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

2014-10-13 Thread Christopher Yeoh
On Mon, 13 Oct 2014 22:20:32 -0400
Jay Pipes jaypi...@gmail.com wrote:

 On 10/13/2014 07:11 PM, Christopher Yeoh wrote:
  On Mon, 13 Oct 2014 10:52:26 -0400
  Jay Pipes jaypi...@gmail.com 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-12 Thread Zhipeng Huang
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 pres...@bannister.us
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 jaypi...@gmail.com 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

2014-10-11 Thread Jay Pipes

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

2014-10-11 Thread Preston L. Bannister
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 jaypi...@gmail.com 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

2014-10-10 Thread Christopher Yeoh
Hi Everett,

Great to see things moving with the API Working Group!

On Thu, Oct 9, 2014 at 9:35 AM, Everett Toews everett.to...@rackspace.com
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