Suggestions for API/ABI Process

[Brian Cameron <Brian Cameron Sun COM>]

I am working to create a better stability story for the GNOME desktop.  However,
one of the things that is causing issues is the fact that the GNOME community
process lacks definition.  Currently the API/ABI process is defined as follows:

  http://developer.gnome.org/dotplan/api_rules.html#ApiFreezeMeaning

However, this definition is too vague, and does not communicate the true nature
of stability in GNOME.  The current definition implies that any API/ABI shipped
with GNOME can be considered stable, which is probably not true.  Some API
(panel-applets, libegg, etc.) is not really intended for public consumption.

Furthermore, it is important to define terms like "interface" and to have a
taxonomy of interface classifications such as "Stable", "Unstable" and "Private"
that have well defined terms.  This way there is no confusion about what is
meant when API/ABI break occurs.  Also, how library versioning and module 
versioning relates to interface stability should be documented.

I have proposed definitions for the GNOME community here:

  http://live.gnome.org/InterfaceSpecification

  (see "Definitions" section #3)

A Wiki is obviously not a good place to try and save such definitions,
since a Wiki can be modified at any time.  It would be better if the
Release Team were willing to review these definitions and move them to a
more stable, authoritative location, such as where the API/ABI process is 
defined on developer.gnome.org.

Really only modules that are defined as "Stable" should be under the API/ABI
rules.  I believe I have highlighted which interfaces in the GNOME stack should
be considered Stable.  Currently this list is based on which modules Sun and
Red Hat should be considered stable, and recommend to their customers.  However,
it is probably a good idea to expand this list to include other interfaces
needed to write a truly GNOMEish application (such as libgnome and libgnomeui).
I recommend that GNOME's API/ABI rules be changed to a more practical
definition that states "use interfaces clearly marked as Stable, and other
interfaces should be avoided."

There should be a list of requirements that a module has to achieve in order
to be considered "Stable".  These requirements should be reasonable, such
as making sure to have complete API documentation (including interface change
information).  I have proposed a list of module requirements on the above
live.gnome.org website.

I am happy to do the work with the module maintainers to get this reasonable
list of Stable modules to meet these requirements, but again it would make
more sense to do this if this process were more formalized by the GNOME
community.  A list of requirements for a module to be considered Stable
should be something communicated on the developer.gnome.website, along with
the API/ABI rules.

The following is the sort of work I would like to do, but it seems a bit
meaningless to do this work without doing the work setting up proper
definitions first.

1) Enhance the README in the module so that it more clearly highlights that
   the module is considered Stable by the module maintainer and the GNOME
   community and is following well-defined API/ABI rules.  This should
   reference the d.g.o website where stability is defined.

2) Some of the modules do not have up-to-date or complete gtk-doc interface
   documentation.  The gtk-doc documentation for Stable modules should
   highlight interface changes from release-to-release (like glib and GTK+
   do).  I am interested in working to enhance these docs so that they are
   complete.  Furthermore, gtk-doc 1.4 now has a feature where you can
   specify the interface stability level for the interfaces in the generated
   docs.  I would like to work with the module maintainers to use this feature
   so the interface stability is more clear.  The interface taxonomy needs
   to be defined somewhere for this to have any meaning.

3) Currently glib and GTK+ make use of an abicheck.sh script which tests
   that the API/ABI hasn't changed when you run "make check".  I would like
   to add this testing to the other Stable modules.  Without the GNOME
   community having requirements for a module to be stable, this doesn't
   really mean much.

However, it is sort of pointless to do the above work unless the API/ABI
rules are well defined in the first place.  This is why I wanted to touch base
with you and see if it would be possible to update the published API/ABI rules
on developer.gnome.org, to be used as a reference.

I think that we could get all this work done in a short timeframe, and have
a much more clear interface stability story for the GNOME destktop.  This
would make it much more clear to ISV's how to best integrate with the
GNOME interfaces, and make GNOME a more practical desktop for ISV's to
work with.

Thoughts?

Brian