[Gtk-sharp-list] API Freeze Policy Adjustment

[Mike Kestner]

We've had some discussion recently about the API freeze for 1.0 that has
resulted in one adjustment to the freeze policy we are planning to
enforce in Gtk#.

At this point, while the API for the 1.0 release series is frozen as was
announced before, there will be one exception to the freeze.  If an API
element can not be used in its current form, it will still be acceptable
to change the API for that element in the 1.0 series.

With Gtk# being a generated binding, there is a considerable amount of
API that simply has not been used or examined yet.  We do not see any
value to library users to maintain unusable API elements instead of
fixing them.

We will not accept changes that make api more semantically correct if
the API can be used in it's current form, though. For example, if a
method exposes an int parameter that is really a bool, we will not
modify that in the 1.0 release series, as users can pass 0 or 1 now. In
this case, please still file a bug report, as in the next development
release we would probably add an overload for the method that takes a
bool and deprecate the int version of the method.

Another example that may pop up that would not be acceptable to change
is if a parameter is marked ref, but it should really be marked out. 
Again, it is possible to use the ref param version, even though it does
require the overhead of initializing your variable first. 

However, if a parameter is really an int[], but the generator has
produced an "out int" parameter (as is the default case for an int*
parameter that has not been marked as an array with metadata), there is
no way to use such a method with the out int semantic.  Anybody that
would try to use it as such would quickly find out that it doesn't work,
and would probably be filing a bug report.  We want to be able to fix
those bugs without having to declare another unstable release series for
the Gnome 2.2 platform.  That is the focus of this adjustment to the
freeze policy.

Unfortunately, most bugfixes to Gtk# require API changes at this point. 
The underlying binding mechanisms are primarily stable.  We think it
better serves the binding's users to be able to fix bugs than to have
solidly frozen but broken API wrappers.

-- 
Mike Kestner <mkestner@ximian.com>