Re: [openstack-dev] [api] Counting resources
detail=concise is not a media type and looking at the grammar in the RFC it wouldn’t be valid. I think the grammar would allow for application/json; detail=concise. See the last line in the definition of the media-range nonterminal in the grammar (copied below for convenience): Accept = Accept : #( media-range [ accept-params ] ) media-range= ( */* | ( type / * ) | ( type / subtype ) ) *( ; parameter ) accept-params = ; q = qvalue *( accept-extension ) accept-extension = ; token [ = ( token | quoted-string ) ] The grammar does not define the parameter nonterminal but there is an example in the same section that seems to suggest what it could look like: Accept: text/*, text/html, text/html;level=1, */* Shaunak On Nov 26, 2014, at 2:03 PM, Everett Toews everett.to...@rackspace.commailto:everett.to...@rackspace.com wrote: On Nov 20, 2014, at 4:06 PM, Eoghan Glynn egl...@redhat.commailto:egl...@redhat.com wrote: How about allowing the caller to specify what level of detail they require via the Accept header? ▶ GET /prefix/resource_name Accept: application/json; detail=concise The Accept request-header field can be used to specify certain media types which are acceptable for the response.” [1] detail=concise is not a media type and looking at the grammar in the RFC it wouldn’t be valid. It’s not appropriate for the Accept header. Everett [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.orgmailto: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] Requesting opinion/guideline on IDs vs hrefs
The discussion about whether flavors should exist as-is or be decomposed is
useful and should continue. It is, however, somewhat orthogonal to the
discussion I was hoping to have on this thread :)
So coming back to the original question (now generalized away from flavors):
how should resource representations refer to other resources?
a) Using an {resource}_id property whose value is a naked ID (e.g. 12345,
1ef1cf90-6f53-11e4-9803-0800200c9a66”), or
b) Using a {resource}_ref property whose value is the URI for the referenced
resource, (e.g. {base}/{resource}/12345), or
c) Using a links property whose value is an array of links, one of which has
an object like { rel: {resource}, href: {base}/{resource}/12345 }, or
d) Similar to c) but using HAL instead, or
e) A combination of a) and c), or
f) A combination of a) and d), or
g) Something else?
So far I've heard two opinions on the above:
- Using a) primarily, but possibly e) for convenience
- Not using c), d), e) or f) since links or _links in JSON+HAL aren't
intended for this purpose
Are there any other opinions on this issue of referencing? If not, I'm thinking
of going with a).
Thank you,
Shaunak
On Nov 17, 2014, at 3:33 PM, Amit Gandhi amit.gan...@rackspace.com wrote:
Agreed it helps with billing. It also allows the customer to make a
choice based on the features offered in a flavor. At the end of the day,
the API works the same way regardless of the flavor selected. The flavor
selection merely gives the customer the experience they are looking for.
I see flavors working this way:
Nova - choosing a flavor that represents the type of compute power you
need. Many combinations could exist.
Zaqar - choosing a flavor that represents the type of messaging you need
(performance, durability, ha, or any combinations of them)
Poppy - choosing a flavor that represents the type of cdn you need
(performance, regionality, cost, or any combination of them)
…and so on…
Within each ‘feature’ there could be multiple options.
Hence I struggle to see how ‘features’ could be exposed directly by the
api’s if that only limits it to one driver of each feature (i.e. There
could be multiple drivers that meet the performance feature for example).
The flavor concept allows operators to package together some of these
features, and offer it to customers - who can then select that flavor via
the API.
In terms of inter-operable clouds, since the API functionality works the
same regardless of flavor, I don’t think it breaks interoperability.
Since operators can define their flavor names themselves and what drives
those flavors, then there is work on the dev to refer to the new flavor at
the new operator’s cloud. But inverting that argument - will every cloud
operator always offer the same flavors? Will some operators prefer to
offer certain flavors only? How do you define flavors (or their features)
in a generic way that allows for the gray area’s in between, and multiple
permutations of the same benefit?
I am curious to explore the idea of not using flavors and replacing the
concept with something more generic (with concrete examples with some of
the existing API’s). It sounds great to me, I just can’t (at this time)
think of how it would work.
Thanks.
Amit.
On 11/17/14, 5:38 PM, Ed Leafe e...@leafe.com wrote:
On Nov 17, 2014, at 3:46 PM, Amit Gandhi amit.gan...@rackspace.com
wrote:
I can see where this makes a lot of sense in API¹s such as Nova¹s where
flavors represent some combination of memory, disk, and cpu performance.
For Nova, flavors emerged more as a billing convenience than anything
technical regarding creating a VM with certain characteristics.
In the case of CDN, the flavor represents a list of CDN providers.
So... you could have a flavor representing a region of the world
(America¹s) consisting of one or more CDN providers with a strong
presence
in those regions.
Or a flavor could represent performance or features offered (number of
edge nodes, speed, etc). And it is up to the operator to define those
flavors and assign one or more appropriate CDN providers to those
flavors.
Again, this seems like the sort of packaging you would need to charge
customers for different levels of service, and not something that you
would need to make a working CDN API.
-- Ed Leafe
___
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] [api] Requesting opinion/guideline on IDs vs hrefs
Hi,
I’ve been working with the Poppy project[1] while they are designing their
APIs. Poppy has a concept of a flavor. A single flavor resource has the URI,
{base}/flavors/{flavor_id}.
Poppy APIs refer to a flavor in their request and/or response representations.
Some representations do this by using the flavor ID (e.g. 12345) while others
use the flavor resource URI (e.g. {base}/flavors/12345).
In this context, I created a bug[2] to settle on one way of referring to a
flavor across all API representations in Poppy. So the question to the API
working group is this:
How should flavors be referred to in Poppy API representations? Some options to
consider:
a) Using a “flavor_id” (or similar) property whose value is the flavor ID (e.g.
12345),
b) Using a “flavor_ref” (or similar) property whose value is the flavor
resource URI (e.g. {base}/flavors/12345),
c) Using a “links” property whose value is an array of links, one of which has
an object like { “rel”: “flavor”, “href”: “{base}/flavors/12345” },
d) Similar to c) but using HAL[3] instead,
e) A combination of a) and c),
f) A combination of a) and d),
g) Something else?
Thanks,
Shaunak
References:
[1] https://wiki.openstack.org/wiki/Poppy
[2] https://bugs.launchpad.net/poppy/+bug/1392573
[3]
https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] API Workgroup git repository
If I have a proposal to make for a guideline, how do I do it? Do I simply create a gerrit review for a file under http://git.openstack.org/cgit/openstack/api-wg/tree/guidelines? Shaunak On Oct 22, 2014, at 3:34 PM, Christopher Yeoh cbky...@gmail.com wrote: On Wed, 22 Oct 2014 20:36:27 + Everett Toews everett.to...@rackspace.com wrote: I notice at the top of the GitHub mirror page [1] it reads, API Working Group http://openstack.org” Can we get that changed to API Working Group https://wiki.openstack.org/wiki/API_Working_Group”? That URL would be much more helpful to people who come across the GitHub repo. It's not a code change so we would need a repo owner to actually make the change. Who should I contact about that? I think this will do it: https://review.openstack.org/130377 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] API Workgroup git repository
Thanks Chris. And am I correct in assuming that no weekly api-wg meetings are currently going on? I don’t see anything here anyway: https://wiki.openstack.org/wiki/Meetings. Shaunak On Oct 22, 2014, at 10:39 PM, Christopher Yeoh cbky...@gmail.commailto:cbky...@gmail.com wrote: On Thu, Oct 23, 2014 at 3:51 PM, Shaunak Kashyap shaunak.kash...@rackspace.commailto:shaunak.kash...@rackspace.com wrote: If I have a proposal to make for a guideline, how do I do it? Do I simply create a gerrit review for a file under http://git.openstack.org/cgit/openstack/api-wg/tree/guidelines? Yes, either additions to the existing files or add new ones if there is nothing currently appropriate. We still need to talk about the exact process for accepting a patch yet, but I was thinking about something along the lines of (and haven't really discussed it with anyone yet): - must be up for at least a week - discussed at a weekly api-wg meeting - no more than one negative vote (ok we might need something to break a deadlock if we really can't get consensus over something but I think there should be a lot of incentive to try very hard to do so). Though for now any setup work in the repository is getting approved by Jay or I if it looks reasonable. Chris Shaunak On Oct 22, 2014, at 3:34 PM, Christopher Yeoh cbky...@gmail.commailto:cbky...@gmail.com wrote: On Wed, 22 Oct 2014 20:36:27 + Everett Toews everett.to...@rackspace.commailto:everett.to...@rackspace.com wrote: I notice at the top of the GitHub mirror page [1] it reads, API Working Group http://openstack.orghttp://openstack.org/” Can we get that changed to API Working Group https://wiki.openstack.org/wiki/API_Working_Group”? That URL would be much more helpful to people who come across the GitHub repo. It's not a code change so we would need a repo owner to actually make the change. Who should I contact about that? I think this will do it: https://review.openstack.org/130377 Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.orgmailto:OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.orgmailto:OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.orgmailto: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] [openstack-sdk-php] Review of face to face meeting on direction for SDK.
Thanks for compiling this, Matt. I think you captured all the major points
here; I just have three additions/changes:
class RackspaceObject extends Object {}
I know this is the exact sample code we put up on the whiteboard and I know we
totally didn’t discuss namespaces at all at the time.
Looking at this snippet now, though, I’m wondering if using namespaces here
would be better so instead of RackspaceObject, the class name would be just
Object but in the Rackspace namespace. Presumably the name of the class being
extended would also be Object (as is the case in the sample code) but that
class would be part of the OpenStack (or Core or something) namespace. Thoughts?
The idea is to use inheritance where needed. This style is quite common in PHP.
I’ll add here something I mentioned during our meeting: We would favor
inheritance for scenarios such as extending an OpenStack-oriented class to a
Rackspace-oriented class. We would favor composition and dependency injection
for cross-cutting concerns such as logging.
Common properties could be protected while uncommon ones, or those we aren't
sure of would be private.
Based on the example we tried out in http://3v4l.org/ (thanks for pointing us
to this site, btw), I thought we were tending towards this convention: all
properties would be private, their accessors (getters/setters) would either be
public or protected; derived classes would access these properties via these
accessor methods, using “parent::somePropertyAccessorMethod()” if necessary.
Thanks,
Shaunak
On Jul 31, 2014, at 6:40 PM, Matthew Farina
m...@mattfarina.commailto:m...@mattfarina.com wrote:
We just completed a meeting on the OpenStack SDK for PHP and this email
attempts to sum up the discussion and action items to come from the meeting.
This was a face to face meeting that included discussions of processes and
architecture.
In attendance were,
- Glen Campbell, Rackspace
- Shaunak Kashyap, Rackspace
- Sam Choi, HP
- Matt Farina, HP
I want to thank everyone who came. This was a productive and good meeting.
The conversation opened with a discussion of process. We discussed the Gerrit
and review process used by the OpenStack community and how Gerrit was
configured for the PHP SDK codebase. Matt took an action item to document the
process.
In addition to the process we discussed reasons a patchset in review would
receive a -1 right away. These include:
- Duplicate effort
- Doesn't meet the coding standard
- The tests fail
- Counter to previously documented decision
- A work in progress (until we come up with a better way to handle that)
- Big feature not tied to a blueprint
We discussed the target audiences for PHP SDK work. The customers are, in
priority order:
1. SDK Consumer
2. Builders of the SDK
3. Extenders of the SDK
Note, #2 and #3 are very close to each other and a distance behind #1.
When we looked at the SDK Consumer we documented we noted a number of projects
that should be able to use the SDK easily. These include:
- Symfony
- Laravel
- Zend Framework
- Wordpress
- Drupal
- Joomla
- Spagetti Code
We also noted the difference between Products (that will be shipped) and
services that use the code.
As part of the process we looked at breaking ties. Since the project is being
entirely worked on by two companies it would be nice to have 3rd parties as a
tie breaker. We discussed using the community. We decided to use a 3rd party
agreed to arbitrator who is willing and we agree to. For example, someone like
Larry Garfield (who we have not contacted yet but is an example of this type of
person).
There were several topics where we came to technical direction.
The directory structure will be the following style...
identity/v2/
identity/v3/
objectStore/v1/
compute/v2/
compute/v3/
A service for a version will be the point of reference. In an attempt to make
extending or replacing the code for a service a viable option we're looking
into interfaces at the level of a service with additional interface definition
at the level of a service version. For example, compute could have an interface
with a reboot method. Then compute v3 could have an interface that extends the
compute interface and adds a compute v3 method/feature. Code consuming the
these can check against the interfaces. Glen took an action item to arrange
feedback on the interface style from some who have worked with this in the past
for other SDKs.
When it comes to extending classes for functionality we came to a conclusion to
use the style...
class RackspaceObject extends Object {}
The idea is to use inheritance where needed. This style is quite common in PHP.
Scoping (public/protected/private) for methods and properties was discussed.
Common properties could be protected while uncommon ones, or those we aren't
sure of would be private. The only public methods would be those defined by the
interface.
An example of the scoping and using
Re: [openstack-dev] [openstack-sdk-php] discussion: json schema to define apis
Yes, thanks Jamie for the very thorough write ups and Matt for the thoughtful
comments.
My comments are inline below. A point of clarification: I’m using “SDK authors”
to mean all of us who are building the SDK and I’m using “SDK consumers” to
mean the end-user developers who will be using the SDK.
Thanks,
Shaunak
On Apr 28, 2014, at 6:29 PM, Matthew Farina m...@mattfarina.com wrote:
Jamie, thanks for going into so much detail.
On Mon, Apr 28, 2014 at 9:28 PM, Matthew Farina m...@mattfarina.com wrote:
While reading this it struck me that we should prioritize the experience of
end-user, that is application developers, over the experience of those
working on the SDK. I don't think we'd ever directly talked about this so I
wanted to take a moment and state it.
What I put in below isn't my full set of questions but I think it's enough
for now.
On Mon, Apr 28, 2014 at 11:34 AM, Jamie Hannaford
jamie.hannaf...@rackspace.com wrote:
Thanks Matt for bringing up these questions - I think having this kind of
discussion is essential for such a big idea. It also helps me clarify my own
thinking towards this issue.
Before I answer, I want to point out that I'm not staunchly for or against
any particular idea. I do think that schemas offer a lot of advantages over
writing user-land code, but I'm more than willing to abandon the proposal if
we all determine there's a stronger and more compelling alternative.
1. Why use schemas instead of userland code?
I've put my answer to this question here:
https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/JSON-schema
Can we look at this from the experience an end user would have? In the
Python SDK they are working on an ORM style system. It's sorta similar to
the system currently in the PHP SDK. For example you could do something like
this in Python,
o = Container.get_by_id('foo').get_object('bar/baz.awesome')
I would imagine something similar in PHP like,
$o = $objectStore-getContainer('foo')-getObject('bar/baz.awesome');
I don't think you can do this using the json schema code I've seen so far.
Can you touch on the experience for developers who are using the library?
For example, the coding style or ability to know what they have access to? I
was just thinking of how magic methods using a schema aren't going to work
for tools that do autocompletion.
Good point about the discoverability aspect. SDK consumers would need to refer
to schemas during development and IDEs might not be able to grok these like
they would a PHP API.
That said, the benefits mentioned on the wiki page still stand. Is there a way
for SDK authors to get the benefits of using schemas while giving SDK consumers
the benefits of an easily- and automatically-discoverable PHP API?
I'm curious about blueprints for the schema support. Things on the mailing
list are great. I'm curious about plans and what's in the blueprints. Do you
have any info on that?
If the other SDKs aren't interested in using json schema, wouldn't that be a
lack of consistency?
This concerns me less. Consistency is useful if there’s a significant overlap
amongst the consumers of different SDKs or, secondarily, amongst the authors of
the different SDKs. I’m not sure there are such significant overlaps.
2. How will debugging work?
I'll highlight two conceivable issues which might need debugging. The first
issue is the API rejecting a request for whatever reason (i.e. a proxy
modifying headers); the second issue is when a data structure returned from
the API fails to validate against a particular schema file.
Issue 1: Malformed requests
There are two reasons why a request would fail: if an end-user stocks it with
bad data, or if something in the middle deforms it. A very easy solution to
the first problem is using schemas to perform basic parameter checking before
a request is serialized. If we know, for example, that the API is expecting a
particular value - or a particular header - the schema is in charge of making
that happen. Performing basic validation catches most errors - and debugging
is very easy due to the exception thrown. If you're ever in doubt, you just
refer to the schema to see what was serialized into a request in the same way
you do for a concrete class method.
If I understand this right, the same code path would be used to perform basic
parameter checking regardless of the upstream service. The specific validation
rules for each upstream service would be represented in the schema. Given this
setup, when an exception is thrown, it would be awesome if we could point the
SDK consumer to the line/section of the schema where the violated validation
rule was defined. This way the exception is actionable for the SDK consumer.
If something in the middle deforms the request, the API will naturally reject
it. When it comes to debugging this issue, all you need to do is wrap your
Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
We had a good discussion on IRC about some of the possible difficulties with this domain: 1) is the developer.example.com standard commercial-based and not open-source? and 2) will developers who want to contribute to OpenStack be confused by this additional subdomain? For 1), I don't believe there's a good open source equivalent we'd want to emulate. For 2), I think the numbers of app developers will far outnumber the contributor developers and their needs outweigh the contributor developers for their own landing page. I actually think developer.openstack.org is perfect - it has the “developer” subdomain which is familiar to API/SDK consumers plus it has the “.org” TLD which has the non-commercial connotation. Agree with #2 that that needs of consumers needs of contributors. When you know, could you share the mechanics of publishing user-facing SDK documentation from its source repo to the appropriate destination on developer.openstack.org? Thanks, Shaunak On Apr 28, 2014, at 2:53 PM, Anne Gentle a...@openstack.org wrote: On Sun, Apr 27, 2014 at 7:57 PM, Shaunak Kashyap shaunak.kash...@rackspace.com wrote: Thanks for your inputs, Matt and Anne. I’m punting on the first question (re: publishing) for now. It sounds like this is a larger discussion and we can make progress on the PHP SDK user-facing documentation without answering it right away. I’ll bring it up again if we don’t have an answer by the time we have something worth publishing. Based on your inputs I’ve created this spec: https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/UserFacingDocumentation. Feel free to comment on it. I intend to start implementing it within a week or so. Great details, Shaunak! I say go for it. I'm working with the Foundation and infra team to get developer.openstack.org registered and then we'll redirect api.openstack.org todeveloper.openstack.org. Look for that change this week. We had a good discussion on IRC about some of the possible difficulties with this domain: 1) is the developer.example.com standard commercial-based and not open-source? and 2) will developers who want to contribute to OpenStack be confused by this additional subdomain? For 1), I don't believe there's a good open source equivalent we'd want to emulate. For 2), I think the numbers of app developers will far outnumber the contributor developers and their needs outweigh the contributor developers for their own landing page. I do want to mitigate these concerns by redesigning the docs.openstack.org landing page to ensure that app devs know there's a site just for them (not just for docs but for downloading tools like SDKs.) I would love to get input on how to best grow the developer site and engage that community further. Thanks, Anne Thank you, Shaunak On Apr 21, 2014, at 11:40 AM, Anne Gentle anne.gen...@rackspace.com wrote: Great questions, Shaunak. Yep I've been thinking about this for a while but not sure I have complete conclusions. More below. On Wed, Apr 16, 2014 at 9:06 PM, Shaunak Kashyap shaunak.kash...@rackspace.com wrote: Hi folks, As part of working on https://blueprints.launchpad.net/openstack-sdk-php/+spec/sphinx-docs, I’ve been looking athttp://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc. Before I start making any changes toward that BP, however, I wanted to put forth a couple of overarching questions and proposals to the group: 1. Where and how should the user guide (i.e. Sphinx-generated docs) be published? Just to give some context and background, we have a User Guide with a Python SDK chapter: http://docs.openstack.org/user-guide/content/ A PHP SDK chapter might be a good addition, if you look at what we have and a pattern that exists, but I'd REALLY like us to break out of the book model and try to create a developer portal with a more page-centered model. What's that? For REST APIs, developers typically expect: developer.example.com - for docs, examples, code, links to download dev kits. api.example.com - for the actual api endpoints. What's tough for us is that there are thousands of OpenStack endpoints by now. A few years back we created api.openstack.org, but didn't realize there's an existing pattern of what devs look for from REST APIs. My bad, I hope we can correct that by creating developer.openstack.org. I know there’s http://docs.openstack.org/. It seems like the logical place for these to be linked off of but where would that link go and what is the process of publishing our Sphinx-generated docs to that place? What's tough about correcting our doc domains going forward is that we have docs.openstack.org/developer for all the contributor dev docs. I do want to continue to separate out the audiences: the contributors are Python devs, the app devs are all languages. I'd like
Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
Thanks for your inputs, Matt and Anne. I’m punting on the first question (re: publishing) for now. It sounds like this is a larger discussion and we can make progress on the PHP SDK user-facing documentation without answering it right away. I’ll bring it up again if we don’t have an answer by the time we have something worth publishing. Based on your inputs I’ve created this spec: https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/UserFacingDocumentation. Feel free to comment on it. I intend to start implementing it within a week or so. Thank you, Shaunak On Apr 21, 2014, at 11:40 AM, Anne Gentle anne.gen...@rackspace.com wrote: Great questions, Shaunak. Yep I've been thinking about this for a while but not sure I have complete conclusions. More below. On Wed, Apr 16, 2014 at 9:06 PM, Shaunak Kashyap shaunak.kash...@rackspace.com wrote: Hi folks, As part of working on https://blueprints.launchpad.net/openstack-sdk-php/+spec/sphinx-docs, I’ve been looking at http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc. Before I start making any changes toward that BP, however, I wanted to put forth a couple of overarching questions and proposals to the group: 1. Where and how should the user guide (i.e. Sphinx-generated docs) be published? Just to give some context and background, we have a User Guide with a Python SDK chapter: http://docs.openstack.org/user-guide/content/ A PHP SDK chapter might be a good addition, if you look at what we have and a pattern that exists, but I'd REALLY like us to break out of the book model and try to create a developer portal with a more page-centered model. What's that? For REST APIs, developers typically expect: developer.example.com - for docs, examples, code, links to download dev kits. api.example.com - for the actual api endpoints. What's tough for us is that there are thousands of OpenStack endpoints by now. A few years back we created api.openstack.org, but didn't realize there's an existing pattern of what devs look for from REST APIs. My bad, I hope we can correct that by creating developer.openstack.org. I know there’s http://docs.openstack.org/. It seems like the logical place for these to be linked off of but where would that link go and what is the process of publishing our Sphinx-generated docs to that place? What's tough about correcting our doc domains going forward is that we have docs.openstack.org/developer for all the contributor dev docs. I do want to continue to separate out the audiences: the contributors are Python devs, the app devs are all languages. I'd like developer.openstack.org to be that landing point for all language devs looking to consume OpenStack cloud resources from any provider. Another difficulty is, how do we govern and review this content? Or do we? Does it fall under the Documentation Program mission? Right now our mission states we only cover core projects (the definition being just a handful of projects) and users as top priority. So I see a developer portal as a user priority. I'm not trying to do a land-grab as a PTL here, but trying to serve users as best we can, and this is definitely an underserved audience. The TC has a stance of code or it doesn't count so stackforge seems like a good starting place. Then core teams can form with deliverables, one of which can be docs. I think we're on the right track here, just making sure I state the potential decision point on how to govern SDKs and their docs and form communities around them. 2. How should the user guide(s) be organized? If I were a developer, I’m probably looking to use a particular OpenStack service (as opposed to learning about the PHP SDK without a particular orientation). So I propose organizing the PHP SDK user guide accordingly: as a set of user guides, each showing how to use the OpenStack PHP SDK for a particular service. Of course, Identity is common to all so it’s documentation would somehow be included in each user guide. This is similar to how OpenStack organizes its REST API user guides - one per service (e.g. http://docs.openstack.org/api/openstack-object-storage/1.0/content/). Agreed. Please use the service name not our crazy code names. :) Further, within each user guide, I propose ordering the content according to popularity of use cases for that service (with some other constraints such as introducing concepts first, grouping similar concepts, etc.). This ensures that the reader can get what they want, from their perspective. Particularly, beginners would get what they came for without having to read too far into the documentation. As an example, I think http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc/oo-tutorial.md does a fine job of walking the user through common Object Store use cases. I would just extend it to gradually introduce the user to more
[openstack-dev] [openstack-php-sdk] Contributing guidelines
Hey PHP SDK folks (although others are welcome to chime in too), I am thinking of adding a CONTRIBUTING.rst to the root of our repo at http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/. My immediate, selfish need is to have a single place where we capture any decisions around contribution process so I don’t have to remember them or rehash them often. Longer term I think this would be useful to all potential contributors - in making them feel welcome and less overwhelmed - especially as the project grows. If you think this would be a useful addition, please read on. Putting on a new contributor’s hat, here are some of the questions (in no particular order) that come to my mind when I encounter a new project: 1. What is the overall development process? 2. I see a bunch of directories and files in the source tree. What do these mean? 3. What do I need to setup in my development environment so I can contribute? 4. Are there any coding standards I should adhere to? 5. I'm ready to submit my first patch. What happens next? 6. How do I run the unit tests? 7. How do I run the integration tests? Can you think of more questions, ones you might’ve had in the past perhaps? I imagine the CONTRIBUTING.rst to be comprised of answers to these questions (but perhaps not necessarily in QA format). I realize that some of these answers would overlap with information that already exists elsewhere. We would link to those sources while still giving our contributors a single starting point within the context of our project. Please note that, at this time, I’m just soliciting approval for having a CONTRIBUTING.rst and coming up with the list of questions that it would answer. I am not (yet) looking for us to come up with all the answers and agree on them as a team. Thoughts? Shaunak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
Hi folks, As part of working on https://blueprints.launchpad.net/openstack-sdk-php/+spec/sphinx-docs, I’ve been looking at http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc. Before I start making any changes toward that BP, however, I wanted to put forth a couple of overarching questions and proposals to the group: 1. Where and how should the user guide (i.e. Sphinx-generated docs) be published? I know there’s http://docs.openstack.org/. It seems like the logical place for these to be linked off of but where would that link go and what is the process of publishing our Sphinx-generated docs to that place? 2. How should the user guide(s) be organized? If I were a developer, I’m probably looking to use a particular OpenStack service (as opposed to learning about the PHP SDK without a particular orientation). So I propose organizing the PHP SDK user guide accordingly: as a set of user guides, each showing how to use the OpenStack PHP SDK for a particular service. Of course, Identity is common to all so it’s documentation would somehow be included in each user guide. This is similar to how OpenStack organizes its REST API user guides - one per service (e.g. http://docs.openstack.org/api/openstack-object-storage/1.0/content/). Further, within each user guide, I propose ordering the content according to popularity of use cases for that service (with some other constraints such as introducing concepts first, grouping similar concepts, etc.). This ensures that the reader can get what they want, from their perspective. Particularly, beginners would get what they came for without having to read too far into the documentation. As an example, I think http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc/oo-tutorial.md does a fine job of walking the user through common Object Store use cases. I would just extend it to gradually introduce the user to more advanced use cases as well, thereby completing the user guide for Object Store. Cc’ing Anne Gentle since she probably has informed opinions on both these questions. Thanks, Shaunak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Setting up a new meeting in openstack-meeting*
Thanks Thierry. I’ve added the meeting to the wiki page. Shaunak On Mar 26, 2014, at 12:25 PM, Thierry Carrez thie...@openstack.org wrote: Shaunak Kashyap wrote: We are looking to setup a recurring IRC meeting in one of the openstack-meeting* rooms for the https://wiki.openstack.org/wiki/OpenStack-SDK-PHP project. What is the process for setting this up (i.e. “reserving” a room for a particular time slot each week)? Is there a formal request to be made somewhere OR could I find an open slot and add our meeting to https://wiki.openstack.org/wiki/Meetings? Just add it to https://wiki.openstack.org/wiki/Meetings If it is the latter, how do we get the meeting added to https://www.google.com/calendar/ical/bj05mroquq28jhud58esggq...@group.calendar.google.com/public/basic.ics? I'm subscribed to changes on the wiki page and do my best reflecting them on the Google calendar. We are looking into replacing this human-intensive process with something more automated, but it's not done yet. Cheers, -- 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] [Heat] Resource dependencies
Thanks for the explanation, Thomas. Appreciate it! Shaunak On Mar 21, 2014, at 12:37 AM, Thomas Spatzier thomas.spatz...@de.ibm.com wrote: Shaunak Kashyap shaunak.kash...@rackspace.com wrote on 21/03/2014 05:26:50: From: Shaunak Kashyap shaunak.kash...@rackspace.com To: openstack-dev@lists.openstack.org openstack-dev@lists.openstack.org Date: 21/03/2014 05:29 Subject: [openstack-dev] [Heat] Resource dependencies Hi, In a Heat template, what does it mean for a resource to depend on another resource? As in, what is the impact of creating a dependency? When a resource depends on another resource, this means that the Heat engine will only start processing this resource as soon as the other resource it depends on has been created. If a resource depends on multiple resources, all those other resources have to be created before processing the depedent resource. I read http://docs.openstack.org/developer/heat/template_guide/ hot_spec.html#resources-section and found this definition of the “depends_on” attribute: This optional attribute allows for specifying dependencies of the current resource on one or more other resources. Please refer to section hot_spec_resources_dependencies for details. Unfortunately, I can’t seem to find the referenced “hot_spec_resources_dependencies” section anywhere. I just checked the source in github and the section is there: https://github.com/openstack/heat/blob/master/doc/source/template_guide/hot_spec.rst#L452 It only looks like the wrong heading markup is used. Nice spotting actually; I will fix it. Thank you, Shaunak ___ 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] [Heat] Resource dependencies
Hi, In a Heat template, what does it mean for a resource to depend on another resource? As in, what is the impact of creating a dependency? I read http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#resources-section and found this definition of the “depends_on” attribute: This optional attribute allows for specifying dependencies of the current resource on one or more other resources. Please refer to section hot_spec_resources_dependencies for details. Unfortunately, I can’t seem to find the referenced “hot_spec_resources_dependencies” section anywhere. Thank you, Shaunak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] User mailing lists for OpenStack projects
Hi folks, I am relatively new to OpenStack development as one of the developers on the unified PHP SDK for OpenStack [1]. We were recently discussing about a mailing list for the users of this SDK (as opposed to it’s contributors who will use openstack-dev@). The purpose of such as mailing list would be for users of the SDK to communicate with the contributors as well as each other. Of course, there would be other avenues for such communication as well (IRC, for instance). Specifically, we would like to know whether existing OpenStack projects have mailing lists for their users and, if so, where they are being hosted. Thanks, Shaunak [1] https://wiki.openstack.org/wiki/OpenStack-SDK-PHP ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [php-sdk] Action items from today's meeting
Thanks for the great meeting today. Here are the action items that came out of it: - [Shaunak] Look into mailing list for user support. How do other OpenStack projects do this? - [Shaunak] Make trivial change to repo to learn OpenStack contribution process - [Jamie] Look into PHPSpec vs. PHPUnit 4. Specific: how does PHPSpec do code coverage? - [Matt] Look into sponsorship from PHP FIG (email Larry Garfield @crell) - [Matt] Consider syncing up with Alex Gaynor about removing dependency on HTTP transport layer - [Matt] Write code to use PSR-4 with intermediate directory (OpenStack) - [Matt] Get with Sam re: regular meeting on Wednesdays at 11EST, then schedule recurring meeting. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [solum] Question about solum-minimal-cli BP
Thanks Angus but I think I have managed to get confused again :) So let me take a step back. From a users' perspective, what is the least number of steps they would need to take in order to have a running application with Solum? I understand there might be two variations on this - git-push and git-pull - and the answer may be different for each. If this is documented somewhere, I'm happy to peruse through that instead; just point me to it. Thanks, Shaunak From: Angus Salkeld [angus.salk...@rackspace.com] Sent: Tuesday, February 18, 2014 6:13 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [solum] Question about solum-minimal-cli BP On 18/02/14 14:19 +, Shaunak Kashyap wrote: Thanks Angus and Devdatta. I think I understand. Angus -- what you said seems to mirror the Heroku CLI usage: a) User runs app/plan create (to create the remote repo), then b) user runs git push ... (which pushes the code to the remote repo and creates 1 assembly, resulting in a running application). If this is the intended flow for the user, it makes sense to me. Just to be clear, I am not totally sure we are going to glue git repo generation to create plan (it *could* be part of create assembly). One follow up question: under what circumstances will the user need to explicitly run assembly create? Would it be used exclusively for adding more assemblies to an already running app? If you are not using the git-push mechanism, but the git-pull. Here you have your own repo (say on github) and there is not a git-repo-generation phase. -Angus Thanks, Shaunak From: Angus Salkeld [angus.salk...@rackspace.com] Sent: Monday, February 17, 2014 5:54 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [solum] Question about solum-minimal-cli BP On 17/02/14 21:47 +, Shaunak Kashyap wrote: Hey folks, I was reading through https://wiki.openstack.org/wiki/Solum/FeatureBlueprints/CLI-minimal-implementation and have a question. If I’m understanding “app create” and “assembly create” correctly, the user will have to run “app create” first, followed by “assembly create” to have a running application. Is this correct? If so, what is the reason for “app create” not automatically creating one assembly as well? On that page it seems that app create is the same as plan create. The only reason I can see for seperating the plan from the assembly is when you have git-push. Then you need to have something create the git repo for you. 1 plan create (with a reference to a git-push requirement) would create the remote git repo for you. 2 you clone and populate the repo with your app code 3 you push, and that causes the assembly create/update. Adrian might want to correct my here tho' -Angus Thanks, Shaunak ___ 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 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [solum] Question about solum-minimal-cli BP
That's exactly what I was looking for. Thank you Angus! Shaunak From: Angus Salkeld [angus.salk...@rackspace.com] Sent: Wednesday, February 19, 2014 5:15 AM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [solum] Question about solum-minimal-cli BP On 19/02/14 08:52 +, Shaunak Kashyap wrote: Thanks Angus but I think I have managed to get confused again :) So let me take a step back. From a users' perspective, what is the least number of steps they would need to take in order to have a running application with Solum? I understand there might be two variations on this - git-push and git-pull - and the answer may be different for each. If this is documented somewhere, I'm happy to peruse through that instead; just point me to it. https://wiki.openstack.org/wiki/Solum/FeatureBlueprints/GitIntegration Thanks, Shaunak From: Angus Salkeld [angus.salk...@rackspace.com] Sent: Tuesday, February 18, 2014 6:13 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [solum] Question about solum-minimal-cli BP On 18/02/14 14:19 +, Shaunak Kashyap wrote: Thanks Angus and Devdatta. I think I understand. Angus -- what you said seems to mirror the Heroku CLI usage: a) User runs app/plan create (to create the remote repo), then b) user runs git push ... (which pushes the code to the remote repo and creates 1 assembly, resulting in a running application). If this is the intended flow for the user, it makes sense to me. Just to be clear, I am not totally sure we are going to glue git repo generation to create plan (it *could* be part of create assembly). One follow up question: under what circumstances will the user need to explicitly run assembly create? Would it be used exclusively for adding more assemblies to an already running app? If you are not using the git-push mechanism, but the git-pull. Here you have your own repo (say on github) and there is not a git-repo-generation phase. -Angus Thanks, Shaunak From: Angus Salkeld [angus.salk...@rackspace.com] Sent: Monday, February 17, 2014 5:54 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [solum] Question about solum-minimal-cli BP On 17/02/14 21:47 +, Shaunak Kashyap wrote: Hey folks, I was reading through https://wiki.openstack.org/wiki/Solum/FeatureBlueprints/CLI-minimal-implementation and have a question. If I’m understanding “app create” and “assembly create” correctly, the user will have to run “app create” first, followed by “assembly create” to have a running application. Is this correct? If so, what is the reason for “app create” not automatically creating one assembly as well? On that page it seems that app create is the same as plan create. The only reason I can see for seperating the plan from the assembly is when you have git-push. Then you need to have something create the git repo for you. 1 plan create (with a reference to a git-push requirement) would create the remote git repo for you. 2 you clone and populate the repo with your app code 3 you push, and that causes the assembly create/update. Adrian might want to correct my here tho' -Angus Thanks, Shaunak ___ 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 ___ 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] [solum] Question about solum-minimal-cli BP
Thanks Angus and Devdatta. I think I understand. Angus -- what you said seems to mirror the Heroku CLI usage: a) User runs app/plan create (to create the remote repo), then b) user runs git push ... (which pushes the code to the remote repo and creates 1 assembly, resulting in a running application). If this is the intended flow for the user, it makes sense to me. One follow up question: under what circumstances will the user need to explicitly run assembly create? Would it be used exclusively for adding more assemblies to an already running app? Thanks, Shaunak From: Angus Salkeld [angus.salk...@rackspace.com] Sent: Monday, February 17, 2014 5:54 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [solum] Question about solum-minimal-cli BP On 17/02/14 21:47 +, Shaunak Kashyap wrote: Hey folks, I was reading through https://wiki.openstack.org/wiki/Solum/FeatureBlueprints/CLI-minimal-implementation and have a question. If I’m understanding “app create” and “assembly create” correctly, the user will have to run “app create” first, followed by “assembly create” to have a running application. Is this correct? If so, what is the reason for “app create” not automatically creating one assembly as well? On that page it seems that app create is the same as plan create. The only reason I can see for seperating the plan from the assembly is when you have git-push. Then you need to have something create the git repo for you. 1 plan create (with a reference to a git-push requirement) would create the remote git repo for you. 2 you clone and populate the repo with your app code 3 you push, and that causes the assembly create/update. Adrian might want to correct my here tho' -Angus Thanks, Shaunak ___ 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] [solum] Question about solum-minimal-cli BP
Hey folks, I was reading through https://wiki.openstack.org/wiki/Solum/FeatureBlueprints/CLI-minimal-implementation and have a question. If I’m understanding “app create” and “assembly create” correctly, the user will have to run “app create” first, followed by “assembly create” to have a running application. Is this correct? If so, what is the reason for “app create” not automatically creating one assembly as well? Thanks, Shaunak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
