Interface Stability in GNOME

[Brian Cameron <Brian Cameron Sun COM>]

A few weeks ago I started a conversation on the gtk-doc alias regarding
ways we could improve gtk-doc to better document GNOME interfaces.  Most
of the suggestions were regarding ways we could document additional
interfaces (environment variables, files, structure/enum changes) and
these suggestions were well received.  One suggestion that has caused
discussion is whether gtk-doc should support interface stability
classifications.

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.  If an interface is not included
in the output, then it is a Project Private interface which
is not guaranteed to be stable and should not be used externally.  The
gtk-docs are also used to highlight deprecated (Obsolete) interfaces.

Does this standard apply to all GNOME libraries that make use of
gtk-doc, or to a specific subset of them?  It would be nice to know
specifically which libraries conform to this best practice and which
libraries would need some attention to get to this point.  If libraries
requiring attention could be highlighted, then I would be interested
in working with those module maintainers to better follow best
practices.

At Sun we use a wider spectrum of interface classifications so that
interface stability levels can be clearly specified for interfaces
that fall somewhere in between 100% Stable and 100% Project Private.
For example, interfaces that are private but must remain stable from
release-to-release to support backwards compatibility and interfaces
that are private but are supported for a specific list of programs.

The following is the current list of interface classifications that are
used at Sun.

+ Standard - The interface is defined and controlled by a standards
  organization.  Icnompatible changes to these interfaces are rare.   This
  stability classification can also apply to interfaces that have been
  adopted (without a formal standard) by an "industry convention" (X/Open,
  MIT X-Consortium, OMG), or even by a single-source (Adobe's Display
  PostScript, Novell's NetWare Protocols, Legato's network backup
  protocols, Berkeley's sendmail) if we expect that the de facto standard
  is unlikely to change incompatibly.

+ Stable - The intention of a Stable interface is to enable arbitrary
  third parties to develop applications to these interfaces, release
  them, and have confidence that they will run on all minor releases
  of the product (after the one in which the interface was introduced,
  and within the same major release). Even at a major release,
  incompatible changes are expected to be rare, and to have strong
  justifications.

+ Unstable - Unstable interfaces are experimental or transitional.
  They are typically used to give outside developers early access
  to new or rapidly changing technology, or to provide an interim
  solution to a problem where a more general solution is anticipated.
  No claims are made about either source or binary compatibility from
  one minor release to the next.

  Any documentation for an Unstable interface must contain warnings
  that these interfaces are subject to change without warning and
  should not be used in unbundled products.

  Given such caveats, customer impact need not be a factor when
  considering incompatible changes to an Unstable interface in a
  major or minor release. Nonetheless, when such changes are introduced,
  the changes should still be mentioned in the release notes for the
  affected release.

+ Obsolete - An interface that is "deprecated" and/or no longer in
  general use. An existing interface may be downgraded from some other
  status (such as Stable or Standard) to Obsolete to encourage customers
  to migrate from that interface before it will be removed (or
  incompatibly changed).

+ Committed Private - For some otherwise-private interfaces, we must maintain
  compatibility from release to release, in order to meet the customer's
  expectations for compatibility of the programs using these interfaces. However,
  we don't want customers to depend on these interfaces directly, and we don't
  want to directly expose these interfaces to customers.

  Our commitment is that a customer's "normal" use of system facilities
  should not allow them to see any incompatible changes to these interfaces.
  Since these interfaces typically span machines by being embodied in media
  or protocols (and since customers cannot upgrade all their machines
  simultaneously), these interfaces can't be changed with the freedom of
  a private interface. Yet, changes to the details of the interface can be
  dramatic, provided the commitment to the customer is maintained. In
  general, Committed Private interfaces should be versioned.

+ Consolidation Private - These are interfaces internal to the consolidation
  that one piece of a consolidation depends on and another piece of the same
  consolidation provides. Changes to these interfaces must be coordinated among
  all providers and users of the interface. Many internal kernel interfaces
  are Consolidation Private interfaces.  Generally these are interfaces that
  have proven convenient for building the consolidation, but which change
  often enough that we're not willing to document them for external use nor
  to commit to their stability.

+ GNOME Private - An interface that can be freely used within the GNOME
  stack itself, but that is not documented for end-users (this is called
  "Sun Private" at Sun).

+ Project Private - Project Private interfaces usually occur when a project
  must communicate between its components across a boundary in the system.
  Project Private interfaces also occur in libraries where one module needs
  to call a private routine in another module in the same library.  Also,
  Project Private interfaces may be provisional or in transition.

Note: Each of the "Private" classes can also be "Contracted" so you can also
have "Contracted Committed Private", "Contracted Consolidation Private",
"Contracted GNOME Private" and "Contracted Project Private".  These stability
levels are the same except that a contract has been put in place between the
provider and consumer of the interface. The contract describes special
arrangements made for the stability of the interface.  This can be used,
for example, to allow exposure of the interface to a specific consumer in
a different consolidation.

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.

Above, I have listed the classifications and definitions we use at Sun.
Perhaps not all of them apply to a project like GNOME, but I wonder if it
would add value for the GNOME community to widen the spectrum of interface
classifications that it uses.  If so, does it make sense to be able to
enhance gtk-doc so that an interface stability tag could be associated with
each interface instead of the stability level being implied by whether an
interface is documented or not?  We've been discussing this a bit on gtk-doc
list, and people have had very different opinions on the idea.  So I thought
it might make more sense to think about this on desktop-devel-list.

Being able to tag each interface would allow a bit more flexibility in
deciding what gets included in the generated documentation.  Certain
non-Stable interfaces might be appropriate to include in the generated
docs if they were clearly labelled as such.

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.

Using this system works well at Sun to help keep track of dependencies
and to ensure that stability levels are clearly labeled.  Such a system
might also benefit the GNOME community.

--

Brian