Re: [Openstack-poc] [Openstack] Thoughts on client library releasing
How do these plans fit with the idea of creating a unified client library (either as one package or several, based on a common core)? On Mon, Jun 18, 2012 at 5:11 PM, Monty Taylor mord...@inaugust.com wrote: We're trying to figure out how we release client libraries. We're really close - but there are some sticking points. First of all, things that don't really have dissent (with reasoning) - We should release client libs to PyPI Client libs are for use in other python things, so they should be able to be listed as dependencies. Additionally, proper releases to PyPI will make our cross project depends work more sensibly - They should not necessarily be tied to server releases There could be a whole version of the server which sees no needed changes in the client. Alternately, there could be new upcoming server features which need to go into a released version of the library even before the server is released. - They should not be versioned with the server See above. - Releases of client libs should support all published versions of server APIs An end user wants to talk to his openstack cloud - not necessarily to his Essex cloud or his Folsom cloud. That user may also have accounts on multiple providers, and would like to be able to write one program to interact with all of them - if the user needed the folsom version of the client lib to talk to the folsom cloud and the essex version to talk to the essex cloud, his life is very hard. However, if he can grab the latest client lib and it will talk to both folsom and essex, then he will be happy. There are three major points where there is a lack of clear agreement. Here they are, along with suggestions for what we do about them. - need for official stable branches I would like to defer on this until such a time as we actually need it, rather than doing the engineering for in case we need it. But first, I'd like to define we, and that is that we are OpenStack as an upstream. As a project, we are at the moment probably the single friendliest project for the distros in the history of software. But that's not really our job. Most people out there writing libraries do not have multiple parallel releases of those libraries - they have the stable library, and then they release a new one, and people either upgrade their apps to use the new lib or they don't. One of the reasons this has been brought up as a need is to allow for drastic re-writes of a library. I'll talk about that in a second, but I think that is a thing that needs to have allowances for happening. So the model that keystone-lite used - create an experimental branch for the new work, eventually propose that it becomes the new master - seems like a better fit for the drastic rewrite scenario than copying the stable/* model from the server projects, because I think the most common thing will be that library changes are evolutionary, and having two mildly different branches that both represent something that's actually pretty much stable will just be more confusing than helpful. That being said - at such a time that there is actually a pain-point or a specific need for a stable branch, creating branches is fairly easy ... but I think once we have an actual burning need for such a thing, it will make it easier for us to look at models of how we'll use it. - API or major-rewrite-driven versioning scheme I was wondering why bcwaldon and I were missing each other so strongly in the channel the other day when we were discussing this, and then I realized that it's because we have one word API that's getting overloaded for a couple of different meanings - and also that I was being vague in my usage of the word. So to clarify, a client library has: * programming level code APIs * supported server REST APIs So I back off everything I said about tying client libs version to server REST API support. Brian was right, I was wrong. The thing that's more important here is that the version should indicate programmer contract, and if it that is changed in a breaking manner, the major number should bump. If we combine that with the point from above that our libraries should always support the existing server REST APIs, then I think we can just purely have statements like support for compute v3 can be found in 2.7.8 and later and people will likely be fine, because it will map easily to the idea just grab the latest lib and you should be able to talk to the latest server Yea? So in that case, the client libs versions are purely whatever they are right now, and we'll increase them moving forward using normal library version thoughts. - room for deprecating old APIs The above then leads us to wanting to know what we do about supported server REST APIs over time, especially since I keep making sweeping statements about should support all available server versions ... How about this as a straw man: Since we're planning on
Re: [Openstack-poc] [Openstack] Thoughts on client library releasing
On Mon, Jun 18, 2012 at 5:56 PM, Monty Taylor mord...@inaugust.com wrote: On 06/18/2012 02:25 PM, Doug Hellmann wrote: How do these plans fit with the idea of creating a unified client library (either as one package or several, based on a common core)? They are kind of orthogonal. At the point where python-openstackclient is ready for release, we'd likely want to manage it the same way. That makes sense. I didn't know if the unification work would be a trigger for the major rewrite branching and versioning issues that you mentioned. On Mon, Jun 18, 2012 at 5:11 PM, Monty Taylor mord...@inaugust.com mailto:mord...@inaugust.com wrote: We're trying to figure out how we release client libraries. We're really close - but there are some sticking points. First of all, things that don't really have dissent (with reasoning) - We should release client libs to PyPI Client libs are for use in other python things, so they should be able to be listed as dependencies. Additionally, proper releases to PyPI will make our cross project depends work more sensibly - They should not necessarily be tied to server releases There could be a whole version of the server which sees no needed changes in the client. Alternately, there could be new upcoming server features which need to go into a released version of the library even before the server is released. - They should not be versioned with the server See above. - Releases of client libs should support all published versions of server APIs An end user wants to talk to his openstack cloud - not necessarily to his Essex cloud or his Folsom cloud. That user may also have accounts on multiple providers, and would like to be able to write one program to interact with all of them - if the user needed the folsom version of the client lib to talk to the folsom cloud and the essex version to talk to the essex cloud, his life is very hard. However, if he can grab the latest client lib and it will talk to both folsom and essex, then he will be happy. There are three major points where there is a lack of clear agreement. Here they are, along with suggestions for what we do about them. - need for official stable branches I would like to defer on this until such a time as we actually need it, rather than doing the engineering for in case we need it. But first, I'd like to define we, and that is that we are OpenStack as an upstream. As a project, we are at the moment probably the single friendliest project for the distros in the history of software. But that's not really our job. Most people out there writing libraries do not have multiple parallel releases of those libraries - they have the stable library, and then they release a new one, and people either upgrade their apps to use the new lib or they don't. One of the reasons this has been brought up as a need is to allow for drastic re-writes of a library. I'll talk about that in a second, but I think that is a thing that needs to have allowances for happening. So the model that keystone-lite used - create an experimental branch for the new work, eventually propose that it becomes the new master - seems like a better fit for the drastic rewrite scenario than copying the stable/* model from the server projects, because I think the most common thing will be that library changes are evolutionary, and having two mildly different branches that both represent something that's actually pretty much stable will just be more confusing than helpful. That being said - at such a time that there is actually a pain-point or a specific need for a stable branch, creating branches is fairly easy ... but I think once we have an actual burning need for such a thing, it will make it easier for us to look at models of how we'll use it. - API or major-rewrite-driven versioning scheme I was wondering why bcwaldon and I were missing each other so strongly in the channel the other day when we were discussing this, and then I realized that it's because we have one word API that's getting overloaded for a couple of different meanings - and also that I was being vague in my usage of the word. So to clarify, a client library has: * programming level code APIs * supported server REST APIs So I back off everything I said about tying client libs version to server REST API support. Brian was right, I was wrong. The thing that's more important here is that the version should indicate programmer contract, and if it that is changed in a breaking manner, the major number should bump. If we combine that with the
Re: [Openstack-poc] [Openstack] Thoughts on client library releasing
Big +1 for automated tagging and releasing (sounds like we're managing wildlife...) from Jenkins! - Gabriel -Original Message- From: openstack-bounces+gabriel.hurley=nebula@lists.launchpad.net [mailto:openstack- bounces+gabriel.hurley=nebula@lists.launchpad.net] On Behalf Of Monty Taylor Sent: Monday, June 18, 2012 3:00 PM To: Joe Heck Cc: openstack-poc@lists.launchpad.net; openst...@lists.launchpad.net Subject: Re: [Openstack] [Openstack-poc] Thoughts on client library releasing On 06/18/2012 02:26 PM, Joe Heck wrote: Monty - Thierry stated it as an assumption last PPB meeting, but I'd like it to be explicit that we have at least a tag on each client library release that we make so that it's possible to distribute a version of the clients. +1000 I didn't want to get too far into implementation details, but the way I'd really like to see this work for the client libs is that releases are actually trigger via jenkins by tags on the repo - so there would literally be no way to release something _without_ a tag. I've got a POC patch to do the tag-based-versioning here: https://review.openstack.org/#/c/8427/ We need to get (aiui) one thing landed to zuul so that we can appropriately trigger on tag events... but that's the plan in my brain hole. On Jun 18, 2012, at 2:11 PM, Monty Taylor wrote: We're trying to figure out how we release client libraries. We're really close - but there are some sticking points. First of all, things that don't really have dissent (with reasoning) - We should release client libs to PyPI Client libs are for use in other python things, so they should be able to be listed as dependencies. Additionally, proper releases to PyPI will make our cross project depends work more sensibly - They should not necessarily be tied to server releases There could be a whole version of the server which sees no needed changes in the client. Alternately, there could be new upcoming server features which need to go into a released version of the library even before the server is released. - They should not be versioned with the server See above. - Releases of client libs should support all published versions of server APIs An end user wants to talk to his openstack cloud - not necessarily to his Essex cloud or his Folsom cloud. That user may also have accounts on multiple providers, and would like to be able to write one program to interact with all of them - if the user needed the folsom version of the client lib to talk to the folsom cloud and the essex version to talk to the essex cloud, his life is very hard. However, if he can grab the latest client lib and it will talk to both folsom and essex, then he will be happy. There are three major points where there is a lack of clear agreement. Here they are, along with suggestions for what we do about them. - need for official stable branches I would like to defer on this until such a time as we actually need it, rather than doing the engineering for in case we need it. But first, I'd like to define we, and that is that we are OpenStack as an upstream. As a project, we are at the moment probably the single friendliest project for the distros in the history of software. But that's not really our job. Most people out there writing libraries do not have multiple parallel releases of those libraries - they have the stable library, and then they release a new one, and people either upgrade their apps to use the new lib or they don't. One of the reasons this has been brought up as a need is to allow for drastic re-writes of a library. I'll talk about that in a second, but I think that is a thing that needs to have allowances for happening. So the model that keystone-lite used - create an experimental branch for the new work, eventually propose that it becomes the new master - seems like a better fit for the drastic rewrite scenario than copying the stable/* model from the server projects, because I think the most common thing will be that library changes are evolutionary, and having two mildly different branches that both represent something that's actually pretty much stable will just be more confusing than helpful. That being said - at such a time that there is actually a pain-point or a specific need for a stable branch, creating branches is fairly easy ... but I think once we have an actual burning need for such a thing, it will make it easier for us to look at models of how we'll use it. - API or major-rewrite-driven versioning scheme I was wondering why bcwaldon and I were missing each other so strongly in the channel the other day when we were discussing this, and then I realized that it's because we have one word API that's getting overloaded for a couple of different meanings - and also that I was being vague in my usage
