[Gtk-sharp-list] API Freeze Policy Adjustment

[Murray Cumming]

Because I saw some more about this on your blog, I thought that I should
comment:

Your plans to add API to stable releases may be incompatible with the
GNOME Platform API practices. These rules were not created by me, but by
the GNOME community around the GNOME 2.0 time.

1. GNOME Platform modules do not add new API during a stable series.
This 
1.1 Avoids confusion by having too many versions of the API.
1.2 Allows new API to be tested properly in unstable releases, instead
of suddenly appearing in a minor stable release.

2. GNOME Platfrom modules usually do not even fix small bits of broken
API in stable phases. We wait for the next development phase, which is
never far away.

However, I break these rules sometimes myself in gtkmm, though very
rarely. I probably shouldn't. For instance,
a) In a stable branch, I have made very small changes to API to make
that API usable, when we have made some simple but embarassing mistake.
b) In a new branch, I have completely redone large parts of API if the
original API was unusable, because there is no chance that that would
break existing applications.

Gtk# 1.0 is not part of the GNOME Platform Bindings, but this will be
relevant if you plan to add Gtk# to the GNOME Platform Bindings in
future. Hopefully you will have dealt with any serious API errors before
then.

You can find more about the GNOME Platform Bindings rules here:
http://developer.gnome.org/dotplan/

On Fri, 2004-06-18 at 14:52 -0500, Mike Kestner wrote:
> 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.
> 
-- 
Murray Cumming
murrayc@murrayc.com
www.murrayc.com
www.openismus.com