Re: Interface Stability in GNOME

[Brian Cameron <Brian Cameron Sun COM>]

Ryan:

> > > Absolutely.  I started to gather this information at one point to put
> > > into my tutorial
> > > (http://www.gnome.org/~newren/tutorials/developing-with-gnome/html/ch05.html#library-overview),
> > > but I fear part of the information I had may have been wrong and I
> > > wasn't able to get a full listing (well...got too distracted by
> > > hacking on Metacity to do it).  I really did want to list each library
> > > as stable or unstable, as much for my own information as for putting
> > > it in the guide for others.
> >
> > As an aside, I think the most useful categorisation is probably
> > Stable/Unstable/Private. So
> > GDK/GTK/ATK/Pango/GConf/gnome-vfs/libbonobo*/ORBit2 are Stable (surely
> > anything in the Developer Platform should be stable?),
> > libgnome-keyring/gstreamer etc. are Unstable, and
> > libwnck/libegg/eel/gal/libgnome-desktop etc. are Private.
>
> I was just thinking to myself is its not simpler and more flexible to
> define a two dimensional metric: Stable/Unstable, Public/Private, with
> Obsolete as a nice singular point. With all those points being relative
> to ISVs.

Another way of thinking of this matrix is as follows:

Stable   - Stable and Public
Unstable - Unstable and Public
Private  - Stable and Private
Internal - Unstable and Private

The advantage of using keywords instead of a matrix is that we are really
talking about a spectrum of datapoints.  Some "Stable and Public" interfaces
are more stable than others, such as when they are well-specified by an
organization that has a good reputation for making solid standards.  So,
by using keywords, additional keywords can be inserted into the list of
stability levels as needed.  Over time, the spectrum can be fleshed out in
this way.  It's also possible to communicate a spectrum of datapoints in
a 2-dimensional fashion, but it could get more complicated.

For example, at Sun we have a half-dozen different subclassifications of
Stable and Private to highlight the degree of stability.  Some Private
interfaces are Stable only within particular contexts that can be
clearly specified and defended (who can use it, how it can be used,
why a cross-boundry private/stable interface is the best way to achieve
a stated requirement).  An advantage of such documentation is that other
applications might also find a need for making use of such private
interfaces, so a mechanism for allowing interfaces to evolve from
Private/Stable to Public/Stable is useful.  Over time, many interfaces
start out as Private, start accepting a few usages in a Private fashion,
become well-used enough to be considered Unstable, and then become
Public as the need for the function becomes more clear.  Good interface
documentation should highlight this evolutionary process, since this
sort of change is really the metric that highlights how stable an
API really is.

Note that it really isn't necessary to document Internal interfaces -
certainly not in any API documentation.  Such interfaces are not
intended to be used externally and changes to Internal interfaces that
cause API breakage should be treated as bugs.  The only documentation
internal interfaces possibly require are aids for internal maintenance.

> I just wanted to second recommendations that you proceed with discussing
> some concrete patches. Discussing theory with this lot will keep you
> going in circles all day. ;)
>
> Off the top of my head:
>
> -first patch gtk-doc to support the interface metrics, and announce that
> not using it is considered a bug
>
> -get gtk-doc to categorize the output by metric (ie Stable Public at the
> top, Unstable Public next with a nice big warning that it may change at
> specific times, then Private etc with a nice big warning against using
> private interfaces, etc)
>
> -get gtk-doc to create graphs that allow the developer to chart the
> functional relationships between modules (hey EVERYONE loves diagrams!)
> Basically anything that is useful than can be squeezed form the
> metadata.

Thanks.  I'm glad to hear that the GNOME community thinks that labelling
interfaces is a good idea.  Now I think we can more comfortably continue
the discussion on the gtk-doc list.  Before this discussion, people on
that list were unsure if specifying stability levels for interfaces would
be something that would be useful or used by the community.  It sounds
like people generally think it is a good idea, and something that would
add value to the gtk-doc tool.

--

Brian