Re: Ruby COMPATIBILITY CONCERNS - Relevant to 1.4.0 release

On 7/15/06, Max Bowsher <maxb1@ukf.net> wrote:
> In r20677, I deleted a typemap that had been added to the Ruby bindings
> since 1.3.x, which caused an undeniable compatibility break, by changing
> the return type of svn_repos_get_committed_info().

The Ruby bindings don't make any compatibility promises. According to
subversion/bindings/swig/INSTALL,
   "The Ruby bindings API may change incompatibility as development proceeds."

I'd recommend reverting r20677, because it deletes a useful feature.

> This isn't anyone's deliberate fault, but collectively as a team, I
> think we've failed to explicitly define a compatibility policy for the
> Ruby bindings.

It's a good idea to define a compatibility policy. The Python bindings
never defined a compatibility policy. As a result, the Python bindings
API is essentially frozen. In the Python bindings, we don't know which
APIs folks are using, so we are forced to assume that every API is
frozen. This is a bad situation.

Because SWIG generates code automatically, many of the APIs generated
by SWIG have never been reviewed by human eyes. Before we promise that
an API will never change, let's make sure that function has explicit
documentation, which spells out the types of its parameters and return
values. At this point, assuming that everyone agrees that the new API
looks good, we can mark the API as 'frozen'.

How can we mark APIs as frozen? In the Mozilla project, they mark
frozen APIs by adding a '@status FROZEN' marker to the API
documentation [1].

After an API is frozen, we can still make changes to the API, as long
as they don't break compatibility. For example, in Ruby, we can still
add extra parameters. However, we can't, for example, change the type
of a parameter without revving the API.

Cheers,

David

[1]: http://www.mozilla.org/projects/embedding/Mozilla_API_freezing.html

-- 
David James -- http://www.cs.toronto.edu/~james
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org