You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Eric Evans <ee...@rackspace.com> on 2010/01/06 21:23:38 UTC
API versioning
I'd like to propose a change to the way we version our API.
Currently, we publish a version string via the thrift method
get_string_property("version"). This version string always moves in
lock-step with the current release, i.e. 0.4.0-beta2, 0.5.0-rc3, etc.
There is no useful correlation that can be made like this. If a client
API worked with 0.5.0-beta1, it might or might not work with
0.5.0-beta2. I think we can do better.
I propose that we return a string composed of joining two integers with
a ".", where the integers represent a major and minor respectively. The
rules for incrementing these would be simple:
1. If it is absolutely breaking, then the major is incremented by one.
For example, changing the number or disposition of required arguments.
2. If it will result in an API that is backward-compatible with the
previous version, then the minor is incremented. For example, if a new
method is added.
This would provide client API authors the tools necessary to ensure
compatibility at runtime, and to better manage the life-cycle of their
projects.
What does everyone think?
--
Eric Evans
eevans@rackspace.com
Re: API versioning
Posted by Ted Zlatanov <tz...@lifelogs.com>.
On Wed, 06 Jan 2010 14:23:38 -0600 Eric Evans <ee...@rackspace.com> wrote:
EE> I'd like to propose a change to the way we version our API.
EE> Currently, we publish a version string via the thrift method
EE> get_string_property("version"). This version string always moves in
EE> lock-step with the current release, i.e. 0.4.0-beta2, 0.5.0-rc3, etc.
EE> I propose that we return a string composed of joining two integers with
EE> a ".", where the integers represent a major and minor respectively. The
EE> rules for incrementing these would be simple:
Wonderful idea.
Ted
Re: API versioning
Posted by Jonathan Ellis <jb...@gmail.com>.
On Wed, Jan 6, 2010 at 2:47 PM, Eric Evans <ee...@rackspace.com> wrote:
> On Wed, 2010-01-06 at 14:29 -0600, Jonathan Ellis wrote:
>> The 0.5 api is a superset of the 0.4 one in method names and
>> arguments, but the exceptions declared are different, so client code
>> in compiled languages with checked exceptions (only Java?) probably
>> needed some light editing to upgrade.
>
> That still breaks existing code though. Would you not bump the major for
> such a case?
I guess that is fine, although it still feels like this introduces
confusion for people whose code is NOT affected (i.e. most non-java
languages).
I guess ultimately there is no substitute for reading release notes.
-Jonathan
Re: API versioning
Posted by Eric Evans <ee...@rackspace.com>.
On Wed, 2010-01-06 at 13:40 -0800, Anthony Molinaro wrote:
> > What would be the rules governing that 3rd value?
>
> I usually like the first to be non-compatible changes, the second
> to be new functionality which is backward compatible and the third
> to be bugfixes. In the case of the .thrift file the third value
> might be for adding comments or something like that.
Comments aren't accessible to the client; I'm not sure I see the point
in exposing that remotely.
--
Eric Evans
eevans@rackspace.com
Re: API versioning
Posted by Anthony Molinaro <an...@alumni.caltech.edu>.
On Wed, Jan 06, 2010 at 02:47:26PM -0600, Eric Evans wrote:
> On Wed, 2010-01-06 at 14:29 -0600, Jonathan Ellis wrote:
> >
> > One question: do we need a 3-tuple?
>
> What would be the rules governing that 3rd value?
I usually like the first to be non-compatible changes, the second
to be new functionality which is backward compatible and the third
to be bugfixes. In the case of the .thrift file the third value
might be for adding comments or something like that.
> > The 0.5 api is a superset of the 0.4 one in method names and
> > arguments, but the exceptions declared are different, so client code
> > in compiled languages with checked exceptions (only Java?) probably
> > needed some light editing to upgrade.
>
> That still breaks existing code though. Would you not bump the major for
> such a case?
I would agree that you should bump the major for this change. Even if
some languages would not be affected, its better for people to be
alerted. If they know enough not to update their stuff fine, otherwise
you'll have fewer issues if people are forced to update.
-Anthony
--
------------------------------------------------------------------------
Anthony Molinaro <an...@alumni.caltech.edu>
Re: API versioning
Posted by Eric Evans <ee...@rackspace.com>.
On Wed, 2010-01-06 at 14:29 -0600, Jonathan Ellis wrote:
>
> One question: do we need a 3-tuple?
What would be the rules governing that 3rd value?
> The 0.5 api is a superset of the 0.4 one in method names and
> arguments, but the exceptions declared are different, so client code
> in compiled languages with checked exceptions (only Java?) probably
> needed some light editing to upgrade.
That still breaks existing code though. Would you not bump the major for
such a case?
--
Eric Evans
eevans@rackspace.com
Re: API versioning
Posted by Jonathan Ellis <jb...@gmail.com>.
+1, the release version is only tenously related to the API version
and tracking the latter separately would be much more useful to
clients for the reasons you gave.
One question: do we need a 3-tuple?
The 0.5 api is a superset of the 0.4 one in method names and
arguments, but the exceptions declared are different, so client code
in compiled languages with checked exceptions (only Java?) probably
needed some light editing to upgrade.
I'm also happy to just ignore that until someone actually complains though. :)
-Jonathan
On Wed, Jan 6, 2010 at 2:23 PM, Eric Evans <ee...@rackspace.com> wrote:
>
> I'd like to propose a change to the way we version our API.
>
> Currently, we publish a version string via the thrift method
> get_string_property("version"). This version string always moves in
> lock-step with the current release, i.e. 0.4.0-beta2, 0.5.0-rc3, etc.
>
> There is no useful correlation that can be made like this. If a client
> API worked with 0.5.0-beta1, it might or might not work with
> 0.5.0-beta2. I think we can do better.
>
> I propose that we return a string composed of joining two integers with
> a ".", where the integers represent a major and minor respectively. The
> rules for incrementing these would be simple:
>
> 1. If it is absolutely breaking, then the major is incremented by one.
> For example, changing the number or disposition of required arguments.
>
> 2. If it will result in an API that is backward-compatible with the
> previous version, then the minor is incremented. For example, if a new
> method is added.
>
> This would provide client API authors the tools necessary to ensure
> compatibility at runtime, and to better manage the life-cycle of their
> projects.
>
> What does everyone think?
>
>
> --
> Eric Evans
> eevans@rackspace.com
>
>
Re: API versioning
Posted by Joe Stump <jo...@joestump.net>.
On Jan 6, 2010, at 1:23 PM, Eric Evans wrote:
> What does everyone think?
+1 from me.
--Joe
Re: API versioning
Posted by Eric Evans <ee...@rackspace.com>.
On Wed, 2010-01-06 at 16:55 -0600, Eric Evans wrote:
> On Wed, 2010-01-06 at 16:33 -0600, Denny Abraham wrote:
> > This seems similar enough to the semantic versioning spec
> > http://semver.org/. (minus the third value) that it may be convenient
> > and worthwhile to implement the full spec.
>
> The third value here is for "backward compatible bug fixes", (as others
> here have suggested). The wording on the page eludes to changes that
> "fix incorrect behavior", or "these are changes that could create
> problems if the library relied on buggy behavior" (my words).
>
> I can get on board with that.
>
> So that would make, x.y.z where x is major, y is minor, and z is patch
> level. The major is bumped for breaking changes, the minor is bumped for
> changes in features or functionality that are backward compatible, and
> the patch level is bumped for every other change.
>
FYI, this was put in place in CASSANDRA-686. The current API version is
now "1.0.0".
Thanks everyone.
--
Eric Evans
eevans@rackspace.com
Re: API versioning
Posted by Eric Evans <ee...@rackspace.com>.
On Wed, 2010-01-06 at 16:33 -0600, Denny Abraham wrote:
> This seems similar enough to the semantic versioning spec
> http://semver.org/. (minus the third value) that it may be convenient
> and worthwhile to implement the full spec.
The third value here is for "backward compatible bug fixes", (as others
here have suggested). The wording on the page eludes to changes that
"fix incorrect behavior", or "these are changes that could create
problems if the library relied on buggy behavior" (my words).
I can get on board with that.
So that would make, x.y.z where x is major, y is minor, and z is patch
level. The major is bumped for breaking changes, the minor is bumped for
changes in features or functionality that are backward compatible, and
the patch level is bumped for every other change.
--
Eric Evans
eevans@rackspace.com
Re: API versioning
Posted by Denny Abraham <de...@gmail.com>.
+1
This seems similar enough to the semantic versioning spec
http://semver.org/. (minus the third value) that it may be convenient
and worthwhile to implement the full spec.
On Wed, Jan 6, 2010 at 3:58 PM, Eric Evans <ee...@rackspace.com> wrote:
> On Thu, 2010-01-07 at 08:41 +1100, Ian Holsman wrote:
>> can you add a new method api_version?
>> some people will probably still want to know the version of the
>> software being run, and it is still useful info to have for
>> operational issues.
>
> Yeah, you could, and that was what I had in mind initially. The
> conclusion I came to though was that with a properly versioned API, the
> software version was really only of interest to operations, and that it
> would be better published along with the rest of our management info,
> (via JMX).
>
>> +1 on the numbering scheme.
>>
>> as for breaking something that works (ie a client library), you can
>> make the client library just have a 'SUPPORTED_VERSION' api call and a
>> 'reported_version' api call, and let the application decide.
>
> Sure.
>
> --
> Eric Evans
> eevans@rackspace.com
>
>
Re: API versioning
Posted by Eric Evans <ee...@rackspace.com>.
On Thu, 2010-01-07 at 08:41 +1100, Ian Holsman wrote:
> can you add a new method api_version?
> some people will probably still want to know the version of the
> software being run, and it is still useful info to have for
> operational issues.
Yeah, you could, and that was what I had in mind initially. The
conclusion I came to though was that with a properly versioned API, the
software version was really only of interest to operations, and that it
would be better published along with the rest of our management info,
(via JMX).
> +1 on the numbering scheme.
>
> as for breaking something that works (ie a client library), you can
> make the client library just have a 'SUPPORTED_VERSION' api call and a
> 'reported_version' api call, and let the application decide.
Sure.
--
Eric Evans
eevans@rackspace.com
Re: API versioning
Posted by Ian Holsman <ia...@holsman.net>.
Hi Eric.
can you add a new method api_version?
some people will probably still want to know the version of the software being run, and it is still useful info to have for operational issues.
+1 on the numbering scheme.
as for breaking something that works (ie a client library), you can make the client library just have a 'SUPPORTED_VERSION' api call and a 'reported_version' api call, and let the application decide.
On Jan 7, 2010, at 7:23 AM, Eric Evans wrote:
>
> I'd like to propose a change to the way we version our API.
>
> Currently, we publish a version string via the thrift method
> get_string_property("version"). This version string always moves in
> lock-step with the current release, i.e. 0.4.0-beta2, 0.5.0-rc3, etc.
>
> There is no useful correlation that can be made like this. If a client
> API worked with 0.5.0-beta1, it might or might not work with
> 0.5.0-beta2. I think we can do better.
>
> I propose that we return a string composed of joining two integers with
> a ".", where the integers represent a major and minor respectively. The
> rules for incrementing these would be simple:
>
> 1. If it is absolutely breaking, then the major is incremented by one.
> For example, changing the number or disposition of required arguments.
>
> 2. If it will result in an API that is backward-compatible with the
> previous version, then the minor is incremented. For example, if a new
> method is added.
>
> This would provide client API authors the tools necessary to ensure
> compatibility at runtime, and to better manage the life-cycle of their
> projects.
>
> What does everyone think?
>
>
> --
> Eric Evans
> eevans@rackspace.com
>
--
Ian Holsman
Ian@Holsman.net