Interface Stability

Sun has been wanting to get a better handle on interface stability in GNOME. Sun has an internal ARC (Architecture Review Process), and to follow the process we need to provide documentation that resembles the following. I have been working with ARC to try and come up with a documentation template that will meet both Sun internal needs and also be a useful reference for the GNOME community. It will likely refer to information contained in other documents (GNOME ISV Guide, Sysadmin Guide, gtk-docs, etc.). This is still very much a first draft, so I would appreciate any comments from the interested people.

Project Description

This project is to create a mechanism for reviewing interface change in each unstable and stable release of GNOME. This information is intended to be useful to ISV's, who might be considering using or depending upon GNOME interfaces. This document will highlight which GNOME interfaces are considered stable by the various distributions, and which interfaces may be used with confidence. This document will also highlight areas where instability has been noticed in the GNOME stack, and recommended workarounds to address problems ISV's might face due to GNOME interfaces changes. Since GNOME is free software, it is always possible to enhance the code for better backwards compatiblity support, so feedback from ISV's is welcome. Problems experienced, workarounds, and features that would be useful to better support would all be useful information.

This document will be reviewed by Sun's Architectural Review Committee (ARC) and will be placed in a public location, somewhere it can easily be edited by those with useful input. Perhaps would be a good location. Interested members of the GNOME community will therefore be able to assist in maintaining this information and participate in the review process.

Feedback and recommendations from both the ARC review, and GNOME community review will help to provide direction for future GNOME development.


GNOME is a complex system which consists of many dozens of components. A small set of core libraries are defined as Stable.

Stable Interfaces as defined by Sun

  • Glib -- a set of C APIs which provide a portable platform for types, threads, and objects
  • GTK+ -- the GNOME widget set and drawing APIs
  • Pango -- a library for layout and rendering of text, with an emphasis on internationalization; it forms the core of text and font handling for GTK+
  • popt -- a library for enhanced commandline processing
  • libglade -- a library for building GUIs from XML descriptions
  • atk -- a toolkit library for providing accessibility to GTK+ programs

Note that Sun's man pages declare these interfaces to be Evolving. Sun's ARC has determined that "Evolving" has the same meaning as "Stable". All other GNOME interfaces are declared as "External" which has the same meaning as "Unstable".

Stable Interfaces as defined by Red Hat

  • GTK+ -- the GNOME widget set and drawing APIs
  • GConf -- GNOME configuration managment
  • libgnomeprint -- GNOME print management
  • libgnnomeprintui -- GNOME print user interface
  • libglade -- a library for building GUIs from XML descriptions

The Red Hat list was provided in an email from Havoc Pennington sent on May 6, 2005. It would be useful to get feedback about what ISV recommendations are coming from other GNOME distros.

Only those libraries which have clear stability guarantees from the GNOME community itself can reasonably be considered Stable by an ISV. All others should be Private. Companies should consider defining a more common ISV stability promise.

In addition to the above components, certain ISV interfaces are declared as Stable. These include interfaces needed for a non-GNOME program (100% Java for example) to integrate with the desktop. The GNOME community is in the process of writing an ISV Guide which will highlight these interfaces. Most of these interfaces follow specifications and are therefore unlikely to change. In summary, these interfaces include:

  • Integration with the GNOME Application (Launch) menu and for launchers
  • Integration of application specific mime information with the GNOME MIME database
  • Integration of application icons into themes (such as those themes required for accessibility support)
  • Specifying a program is to be started with the user session via GNOME session management
  • File formats and file installation locations for files required by these interfaces

All other interfaces shipped with the GNOME stack are defined as External, which should be considered Private by ISV's and should not be considered for use. Havoc Pennington said "stay away from writing panel applets, libgnomeui, libwnck, ... [insert whatever else]". This document will focus documenting Stable interface stability and changes to Private interfaces will only be discussed when those changes could affect an ISV.

Motivation, Goals, and Requirements




The goal of this document is to highlight which GNOME interfaces are stable. Interfaces include library API, file installation locations, the format of files which require customization by ISV's, and other ISV integration points. Furthermore, this document highlights how interfaces are added, changed, deprecated, or removed from GNOME for each release. Some of this information is located in other locations (such as and the GNOME library gtk-docs, the GNOME System Administrations Guide, etc.), so this document will contain links to the appropriate resource rather than duplicating information. It will highlight differences release-to-release.


Each of the following requirements should be met by this document. This document will evolve to contain the following information that will be of use to ISV's:

  • The GNOME project needs to effectively communicate which GNOME interfaces are stable to its ISV's and end users. At Sun, stability information is included in man pages, which is why Sun ships man pages for stable libraries. The GNOME community uses gtk-doc, which has been enhanced to allow module maintainers the ability to specify stability levels for interfaces. Changes to interfaces and changes to interface stability need to be documented.
  • Integrated ABI testing and verification with the build system, so ABI reports are generated for libraries that are considered Stable. The report should highlight what interfaces/symbols are added, changed, deprecated, or removed from the library.
  • Sanity test for QA testing GNOME from a Stability perspective. Issues uncovered, and available workarounds should be documented.
  • All programs installed to /bin, and /sbin must have man pages. Within Sun, all stable libraries must also have man pages which point to the location of the installed gtk-docs.
  • Logic that contains encryption logic must be documented since this affects distro's and ISV's, who may require export control licenses.
  • Logic that contains known or suspected intellectual property issues must be highlighted. Such code may be shipped by a distribution if they own an appropriate license. Specifically, this includes GStreamer plugins which contain proprietary codecs protected under IP laws.
  • Any GPL'ed libraries that are shipped with the Sun GNOME stack should be highlighted since linking against them affects the licensing of ISV's who may want to use the interfaces.
  • Code changes relating to security should be highlighted in the document even if the interface is Private.
  • Performance should be not be unreasonably impacted by upgrading to a new version of GNOME. Changes that affect GNOME performance should be highlighted. Where appropriate, making it possible to disable such features is recommended.

Much of this information is contained in other documents, so this document will contains links to those resources where appropriate.

Process Recommendations

In order to verify ABI compatibility for Stable libraries, the GNOME release team should integrate ABI testing with the build process so that an ABI report for each library can be easily generated for ARC materials. Since the ARC process will likely accellerate with OpenSolaris?, being able to generate such reports on-demand will be necessary.

In order to test the stability of Stable interface, the GNOME team must resource QA testing to verify stability. This includes installing a suite of programs from previous Solaris releases and running sanity tests to ensure that the applications built with previously shipped interfaces will continue to work properly and continue to properly integrate with the desktop. The Sun GNOME QA team believes that they can add such testing to their process.

GNOME modules document their public API definition in gtk-doc format, generated when the code is built and shipped in /usr/share/gtk-doc. gtk-docs for Stable modules should be archived somewhere in a Stable location for each stable and unstable release for easy reference.

It would be useful if ISV's had a more clear mechanism for communicating with the GNOME community. It would perhaps be useful to setup a GNOME mail alias for ISV's to discuss issues, and to discuss issues that affect ISV's, such as changes to interfaces they might depend upon.


Post a Comment:
  • HTML Syntax: NOT allowed



« July 2016