Re: Interface Stability in GNOME

[Havoc Pennington <hp redhat com>]

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.

> 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.

> 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.

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).

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.

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" ;-)

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.

Havoc