Version numbering, the release, and backwards compatibility

[Mark Ramm]

Here's the TLDR summary:

After today's developer discussions, I believe we have some consensus 
the about the upcoming public release of Juju-core, we believe it should 
be version 1.10.0.

We also had agreement based on the current state that the new go based 
juju core should become the default, both in Universe and in the ~juju 
PPA.  The python version 0.7 should also be explicitly installable via 
update alternatives, and that 0.7 will likely be the "end of life" for 
pyjuju.

Full context:

While huge progress has been made over the last month, I don't believe 
we have enough charm testing completed to be completely ready to go for 
the 2.0 moniker in this first release.

And our convention is that odd minor release numbers are "development" 
versions, we would rather not directly put a dev version into the release.

So, the suggestion was made to go with 1.10.0.   The rest of this e-mail 
is an attempt to spell out what that means for our development process.

Once we release 1.10.0 two things should happen:

  * ongoing development work will move to 1.11.x
  * critical bugfixes and security issues should be handled by fixing
    both the current working tree, and backporting to 1.10.x

Compatibility breaking changes to the websocket API, the command line 
interface, the mongo database schema, or agent communications should be 
flagged immediately on juju-dev, and a smooth upgrade process should be 
mapped out as soon as they are discovered.

We should be promising basic compatibility, and a fully supported 
upgrade path from 1.10.x to 1.12.x and to 2.0.x.  We should be 
developing MongoDB schema update support, and all the other tools 
necessary to manage these upgrades in a sane way.

We are in a somewhat difficult position at the moment in which the 
"effective API" of juju includes:

  * Mongo DB Schema
  * Command Line input/output
  * and the websocket API

We have different levels of documentation and testing for each of these 
three "public interfaces" and there is code that talks to all three. So, 
determining what is a real backwards incompatible change may not always 
be easy, but whenever any of these things change in a backwards 
incompatible way, we will have to increment the major version number.

Ultimately it is our plan to get to the point where the websocket API's 
will become "the critical contract" and the command line client will 
just use that API to talk to the state server(s), as will the agents, 
the GUI, and other third party tools that are part of the ecosystem.

At that point the internal mongo schema will no longer be part of the 
public API, and we could also consider the possibility of breaking out 
the command line API contract from the "core" api, and visioning them 
separately -- but for now our contract uses all three (but we should be 
working very hard to avoid adding any new components that talk directly 
to MongoDB).

If I've missed anything from our discussions, or anybody has a proposal 
on how to handle all of this more cleanly, now is the time to raise issues.

--Mark Ramm




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20130411/8925f7bb/attachment.html>