atom feed19 messages in net.launchpad.lists.openstack[Openstack] Thoughts on client librar...
FromSent OnAttachments
Monty TaylorJun 18, 2012 2:10 pm 
Doug HellmannJun 18, 2012 2:24 pm 
Joe HeckJun 18, 2012 2:25 pm 
Kevin L. MitchellJun 18, 2012 2:37 pm 
Monty TaylorJun 18, 2012 2:56 pm 
Monty TaylorJun 18, 2012 2:59 pm 
Doug HellmannJun 18, 2012 3:05 pm 
Gabriel HurleyJun 18, 2012 5:19 pm 
Mark McLoughlinJun 18, 2012 11:19 pm 
Thierry CarrezJun 19, 2012 2:25 am 
Mark McLoughlinJun 19, 2012 7:10 am 
Thierry CarrezJun 19, 2012 7:47 am 
Mark McLoughlinJun 19, 2012 8:05 am 
Monty TaylorJun 19, 2012 11:06 am 
Daniel P. BerrangeJun 20, 2012 1:25 am 
Mark McLoughlinJun 20, 2012 4:37 am 
Thierry CarrezJun 22, 2012 5:59 am 
Lloyd DewolfJun 22, 2012 3:26 pm 
Endre KarlsonJun 23, 2012 3:10 am 
Subject:[Openstack] Thoughts on client library releasing
From:Monty Taylor (
Date:Jun 18, 2012 2:10:40 pm

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 beginning to run tests of the client libs against previous versions (so we'll test trunk novaclient against essex nova in addition to trunk nova) ... we need support for past versions of servers as long as our automation can sensibly spin up a past version. (Since the support for that API version shouldn't need huge amounts of work moving forward) But there will reach a point where old server versions require stuff that's older than we feel like supporting, and at that point we drop it. (or, more to the point, that we reserve the right in the future to declare that we're going to drop old server API versions - but the general policy is that we'll keep old support until it becomes a pain in the ass)

Does that all sit well with folks?