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)?<br><br><div class="gmail_quote">On Mon, Jun 18, 2012 at 5:11 PM, Monty Taylor <span dir="ltr"><<a href="mailto:mordred@inaugust.com" target="_blank">mordred@inaugust.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">We're trying to figure out how we release client libraries. We're really<br>
close - but there are some sticking points.<br>
<br>
First of all, things that don't really have dissent (with reasoning)<br>
<br>
- We should release client libs to PyPI<br>
<br>
Client libs are for use in other python things, so they should be able<br>
to be listed as dependencies. Additionally, proper releases to PyPI will<br>
make our cross project depends work more sensibly<br>
<br>
- They should not necessarily be tied to server releases<br>
<br>
There could be a whole version of the server which sees no needed<br>
changes in the client. Alternately, there could be new upcoming server<br>
features which need to go into a released version of the library even<br>
before the server is released.<br>
<br>
- They should not be versioned with the server<br>
<br>
See above.<br>
<br>
- Releases of client libs should support all published versions of<br>
server APIs<br>
<br>
An end user wants to talk to his openstack cloud - not necessarily to<br>
his Essex cloud or his Folsom cloud. That user may also have accounts on<br>
multiple providers, and would like to be able to write one program to<br>
interact with all of them - if the user needed the folsom version of the<br>
client lib to talk to the folsom cloud and the essex version to talk to<br>
the essex cloud, his life is very hard. However, if he can grab the<br>
latest client lib and it will talk to both folsom and essex, then he<br>
will be happy.<br>
<br>
There are three major points where there is a lack of clear agreement.<br>
Here they are, along with suggestions for what we do about them.<br>
<br>
- need for "official" stable branches<br>
<br>
I would like to defer on this until such a time as we actually need it,<br>
rather than doing the engineering for in case we need it. But first, I'd<br>
like to define we, and that is that "we" are OpenStack as an upstream.<br>
As a project, we are at the moment probably the single friendliest<br>
project for the distros in the history of software. But that's not<br>
really our job. Most people out there writing libraries do not have<br>
multiple parallel releases of those libraries - they have the stable<br>
library, and then they release a new one, and people either upgrade<br>
their apps to use the new lib or they don't.<br>
<br>
One of the reasons this has been brought up as a need is to allow for<br>
drastic re-writes of a library. I'll talk about that in a second, but I<br>
think that is a thing that needs to have allowances for happening.<br>
<br>
So the model that keystone-lite used - create an experimental branch for<br>
the new work, eventually propose that it becomes the new master - seems<br>
like a better fit for the "drastic rewrite" scenario than copying the<br>
stable/* model from the server projects, because I think the most common<br>
thing will be that library changes are evolutionary, and having two<br>
mildly different branches that both represent something that's actually<br>
pretty much stable will just be more confusing than helpful.<br>
<br>
That being said - at such a time that there is actually a pain-point or<br>
a specific need for a stable branch, creating branches is fairly easy<br>
... but I think once we have an actual burning need for such a thing, it<br>
will make it easier for us to look at models of how we'll use it.<br>
<br>
 - API or major-rewrite-driven versioning scheme<br>
<br>
I was wondering why bcwaldon and I were missing each other so strongly<br>
in the channel the other day when we were discussing this, and then I<br>
realized that it's because we have one word "API" that's getting<br>
overloaded for a couple of different meanings - and also that I was<br>
being vague in my usage of the word. So to clarify, a client library has:<br>
<br>
 * programming level code APIs<br>
 * supported server REST APIs<br>
<br>
So I back off everything I said about tying client libs version to<br>
server REST API support. Brian was right, I was wrong. The thing that's<br>
more important here is that the version should indicate programmer<br>
contract, and if it that is changed in a breaking manner, the major<br>
number should bump.<br>
<br>
If we combine that with the point from above that our libraries should<br>
always support the existing server REST APIs, then I think we can just<br>
purely have statements like "support for compute v3 can be found in<br>
2.7.8 and later" and people will likely be fine, because it will map<br>
easily to the idea "just grab the latest lib and you should be able to<br>
talk to the latest server" Yea?<br>
<br>
So in that case, the client libs versions are purely whatever they are<br>
right now, and we'll increase them moving forward using normal library<br>
version thoughts.<br>
<br>
 - room for deprecating old APIs<br>
<br>
The above then leads us to wanting to know what we do about supported<br>
server REST APIs over time, especially since I keep making sweeping<br>
statements about "should support all available server versions" ... How<br>
about this as a straw man: Since we're planning on beginning to run<br>
tests of the client libs against previous versions (so we'll test trunk<br>
novaclient against essex nova in addition to trunk nova) ... we need<br>
support for past versions of servers as long as our automation can<br>
sensibly spin up a past version. (Since the support for that API version<br>
shouldn't need huge amounts of work moving forward) But there will reach<br>
a point where old server versions require stuff that's older than we<br>
feel like supporting, and at that point we drop it. (or, more to the<br>
point, that we reserve the right in the future to declare that we're<br>
going to drop old server API versions - but the general policy is that<br>
we'll keep old support until it becomes a pain in the ass)<br>
<br>
Does that all sit well with folks?<br>
<br>
Monty<br>
<br>
_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
Post to     : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
More help   : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
</blockquote></div><br>