Re: Interface Stability in GNOME

[Brian Cameron <Brian Cameron Sun COM>]

Havoc:

Thanks for responding.

> On Tue, 2004-12-21 at 16:42 -0600, Brian Cameron wrote:
>
> > My understanding is that the way the GNOME community currently documents
> > interface stability is by deciding whether or not to include an
> > interface in the gtk-docs.  If an interface is included in the gtk-doc
> > output, then it is a Stable interface. 
>
> I haven't really heard this policy, so I guess it doesn't apply to stuff
> I wrote ;-) e.g. libwnck is all kinds of not-stable and has some docs.
>
> My feeling is more that if the function is exported from the shared
> object and present in the normal header files of a public library then
> it's assumed public. But some libraries are wholesale explicitly non-
> public, even though they install headers. And some public libs install a
> thing like gtkprivate.h but if you #include <gtk/gtkprivate.h> and use a
> flag called PRIVATE_GTK_IN_REPARENT then complain that you thought it
> was public you most likely have larger problems.
>
> There are some more ambiguous cases like the backend-only Pango headers
> I guess.

First of all, I'd like to thank you for giving me a better perspective on
what parts of the GNOME stack are considered by the community developers
to be the most and least stable parts.  I think it would be very useful if
these areas could be better documented, so that the parts that are
Stable and the parts that are Unstable or Private are be more clearly
separated.  Would this sort of information be useful to the overall GNOME
community?  Would it be appropriate to have information like this somewhere
on d.g.o?

Second, I'd like to state that my goals are not to make all GNOME
interfaces stable, just to try and help create better documentation that
more clearly highlights which is which.  Since, as you say, the gtk-docs
themselves do not clearly highlight the difference, I don't think this
is specified anywhere currently.

However, I'm a bit unsure how to go about collecting and documenting all
this information.  Should I be talking to each of the module maintainers
independantly and getting them engaged to get this sort of documentation
together, or should we just continue talking about this topic on
desktop-devel until the information is culled out, or another way?

> > As I highlight above, the community seems to break things down into Stable,
> > Project Private, and Obsolete.  One disadvantage with this approach is that
> > it is a bit ambigous.  There does not seem to be much information at
> >  developer.gnome.org explaining the interface stability documentation
> > conventions.  So an end-user might wrongly assume that an undocumented
> > interface is a Stable interface lacking documentation.
>
> I don't think we have headers that mix Project Private with Stable. We
> may have some shared objects that do. But e.g. all of gtk/gtk.h should
> be either Stable or Obsolete, with Obsolete documented.

My understanding is that glib, pango and gtk+ are the 3 libraries in GNOME
that do a good job of ensuring that all exposed interfaces are Stable.  You
highlight that libgnomeprint, GConf and gnome-vfs are also in the running.
What I would like to do is the following:

1. Get confirmation from the community that making more of an effort to
   clearly separate stable/unstable/private interfaces is something that
   would add value to GNOME and the stability of the GNOME stack.

2. Identify what libraries in the GNOME stack would benefit most from
   attention.

3. Identify some practical things that I can do to help improve the
   situation.  I'd prefer to start doing some work that actually helps
   to improve the GNOME documentation now.  However, I'm unsure where to
   start, and I'm unsure what specific changes to the GNOME documentation
   would make the most impact.

If you or anyone can help point me towards some things that need doing,
then I'd love to get started and spend less time talking theory.  :)

> > Another advantage of using the various Private interface classifications
> > is that it encourages people to document the private dependencies that
> > exist between modules.  If a program like metacity requires usage of a
> > private glib or GTK+ interface, this can be clearly documented as a
> > "Contracted Consolidation Private" interface.  This means that the
> > interface might change from release-to-release, but will never change in
> > a way that breaks a specific list of client programs.
>  
> I feel like we might be getting complex before we do the simple thing.

I agree.  While it is perhaps useful or interesting to the GNOME community
to understand how we handle these issues at Sun, I do not think it is
necessary for GNOME to label its interfaces in the same way.  All that
is really desired is for the Stable interfaces that exist to be clearly
separated from Unstable or Private interfaces.  From your response, it
seems the GNOME community hasn't really defined any best practices about
how this should be done.  Perhaps the techniques used by the glib/pango/gtk+
libraries could be extended into a "best practices" that other libraries
could be encouraged to follow?

> The simple thing is that gtk/gtk.h and the dependency headers it
> includes (pango, glib) are public and recommended; and a few other
> libraries as well (the Havoc-and-Owen-hallway-conversation opinion on
> these is libgnomeprint, GConf, and gnome-vfs - these three are
> reluctantly included because even though they aren't that great in some
> ways, in practice we are going to have to keep them back compatible and
> you need their functionality to write a good integrated app).

I will go ahead and contact the maintainers of the libgnomeprint, GConf,
and gnome-vfs modules and see if they can suggest ways I can help improve
their interfaces so that they are more like glib/gtk+/pango.

> We should then explicitly exclude libgnome* and the other random noise
> like libwnck and libpanel-applet.
>
> Until we've done that we could have people using entire wrong
> *libraries*
>
> I do think we should get into the details of which symbols in the
> libraries to use, but let's not miss the forest for the trees.
>
> My suspicion is that for the main ISV-recommended libraries only Stable
> and Obsolete are really interesting categories; the more fine-grained
> classifications seem more relevant to different groups inside one
> company etc. than they do to third-party developers. For a third party
> either they can use it or they can't.

Stable and Obsolete are the two most important interfaces.  Unstable
interfaces can be useful to define if you want to ship a library which
is okay to use for now, but has a known limited life span (perhaps
like libgnome*, libwnck, and libpanel-applet).  Clearly identifying
them somewhere as Unstable makes this message more clear to the ISV.
Private is useful in situations where one module wants to use a private
interface in another module.  Some mechanism to indicate that "it's
okay for that other module to use this interface for a particular
purpose, but others should not use it" is a good idea.  The nice
thing about using interface stability keywords is that they are
grep-able (and also transformable via tools like gtk-doc) and therefore
easier to identify.  This is nicer than ad hoc comments in the code.

> So we should maybe talk about what categories are of interest to GNOME
> developers. One example is e.g. libmetacity-private which can break at
> any time and is only for use by control-center.
>
> We might consider using the "magic -D" more often, e.g. maybe
> libmetacity-private should make you do "-DI_AM_GNOME_CONTROL_CENTER" ;-)

Well, we have to start somewhere.  I suspect that there is much improvement
that could be done in the libraries that we know should be Stable.  If
we focus some attention now to improving these libraries, that will give
us some time to have a better understanding about what to do for libraries
like libmetacity-private.

> But then, I've never seen any hint of anyone considering using
> libmetacity-private, so perhaps we're solving a non-problem in this
> case. libwnck and libpanel-applet are maybe more interesting to think
> about.

Agreed.  I think you've started to point me in some useful direction,
though I would also appreciate any other feedback regarding where
interface stability attention could best be focused.

--

Brian