openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

Thanks for the input, Monty. So the reason I'm suggesting major only is due to our extensions mechanism. We are using extensions to achieve our incremental, non-breaking changes rather than using minor versioning. For example, we have a keypairs extension in the v2 API. We shouldn't go to a v2.1 and add a keypairs resource since that would conflict with the existing extension. We also couldn't remove the extension altogether since that would break the contract we hold with the clients of the API (something you shouldn't to do within minor versions). Personally, I *would* want major/minor if we didn't have extensions…but here we are. Do you have any thoughts on that?

Brian

On Dec 21, 2011, at 6:02 AM, Monty Taylor wrote:

>> Clients should
>> couple only to major numbers. Media types should have their own
>> independent version counters that use major only.
>> 
>> Minor (and bugfix, which is part of minor) should be design time
>> constructs only, basically to name feature seats. Docs, WADL, XSDs, JSON
>> schemas use major+minor.
> 
> I would suggest taking at least learning something from libtool. libtool
> does this stuff really well if you pay attention to the rules. They are
> as follows:
> 
> A version consists of a triple: current:revision:age
> 
> Current should be increased if interfaces have been added, removed or
> changed
> Revision should be incremented if source code has changed, and should be
> set to zero if current is incremented
> Age should be incremented if interfaces have been added. It should be
> set to zero if interfaces have been removed or changed.
> 
> So you have two different things you're tracking - what is the state of
> the interface, and also has the underlying implementation of the
> interface changed. (in theory, two different versions of implementations
> of the v1 interface should be the same - but you _might_ want to be
> paranoid about it, so it's nice to know if it's happened)
> 
> The range of API supported by a thing with that version information is
> current-age. For example:
> 
> 1:0:0 - initial import - this supports interface version 1.
> 1:1:0 - bug fix in something - this supports interface version 1.
> 2:0:1 - added some interface methods - this supports interface versions
> 1 and 2 (code written to use 1:0:0 or 1:1:0 can safely assume this one
> will work)
> 3:0:0 - removed support for interface versions 1 and 3. supports
> interface version 3 only (removing interface elements essentially always
> need for a consumer to go through and make sure that they still work)
> 
> It's a fairly straightfoward set of rules that handle description of
> many of the things below. (the scheme and rules are also already being
> used by massive amounts of software)
> 
> FWIW