Re: platform compatibility policy

[Colm Smyth <Colm Smyth ireland sun com>]

>From: Havoc Pennington <hp redhat com>
>
>Colm Smyth <Colm Smyth ireland sun com> writes: 
>> QA and review are two ways to ensure that the enhancement in no
>> way breaks compatibility. I like the idea of short release cycles,
>> so I really like having automated test scripts and an ABI tester
>> to assure confidence in each release.
>
>I like the idea too, but we don't have _any_ tests right now and
>haven't established that we're going to be able to get people to do
>them.

Ideally every major library would have an automated test suite, but
I don't want to bang that drum. ABI tests don't need people to write
them, they just need each library maintainer to maintain the ABI
database for their library; this takes a little effort to setup
initially, but it's easy to maintain.

>I'm still somewhat concerned about the issue of developer
>confusion. Say you want to target TurboLinux, Red Hat, and Mandrake,
>and Solaris: at the moment you just need to know if they all ship
>GNOME 1.4. But say they have 1.4.2, 1.4.3, 1.4.1, and 1.4.4. Which
>interfaces is it OK to use? Are we going to document things in that
>much detail?

The GNOME web-site should contain clear recommendations for which
interfaces are stable, evolving, etc., along with the library
versions that correspond to those interfaces. A GNOME distribution
should include *all* currently supported library major versions.
I've drafted a document (attached), which is intended to be
an introduction to ABI and API compatibility issues. It doesn't
make a strong statement on policy, that needs to be a short
clear document that the GNOME foundation ratify.

>One concern at the moment is that we don't even have a reasonable test
>harness for automated testing of GUI stuff.

GUI-testing is always difficult; it helps if it's possible to
write a test driver that exercises the functionality code
underneath each GUI, and then use either a record-playback program 
or a GUI-scripting tool for exercising the GUI itself. 

>> This is really an aside, but I don't know how many people have
>> come across the concept of 'extreme programming'; 
>
>I've read the book, and was impressed with its correspondence to lots
>of the methods we use in free software, with the very notable
>exception of the test suite idea. 
>
>I was convinced of the value of the test suite by using one for GConf
>(even though my suite for that kind of sucks and is incomplete, it
>caught dozens of bugs and makes me much more confident about changing
>things).

I think most people who put the effort into developing a test suite
for the first time are surprised by how useful it is. Naturally the
developers of a library are the best people to write the test suite,
since they know the difficult or dodgy parts of the code better than
anyone else.

Colm.

Compatibility in GNOME

The GNOME environment provides a rich framework for developing
applications through a broad set of libraries. It is an important goal
of GNOME that applications built for one release of GNOME will continue
to run on later releases. Supporting this compatibility goal requires
that each release of GNOME supports the public application binary
interface (ABI) of the previous release. GNOME's compatibility policy
(url link here) defines the support provided for applications built on
previous releases of the GNOME platform.

How do GNOME maintainers support compatibility?

The developers of GNOME's pubilc libraries carry most of the
responsibility for maintaining compatbility. It should be possible for
a user of GNOME to upgrade to a newer release of GNOME but to continue
to use an application built against the libraries and header files for
a previous GNOME release.

What is a public application binary interface?

The idea of an application binary interface or ABI is related to the
concept of an application programmers interface or API.

An API is defined by a collection of declarations in a header file:

- prototypes of functions or methods
- declarations of structs or classes
- definitions of pre-processor macros
- data variables

An API is public if it is declared in one of GNOME's public header
files; these are the files installed to the <GNOME>/include tree, for
example /opt/gnome/include/gtk/gtk.h.

An application binary interface or ABI is provided by one or more
shared libraries that implement an API. For example, the Gtk 2.0 API
might be implemented by two shared libraries called libgtk.so.2 and
libgdk.so.2. When an application programmer wants to write an
application using Gtk+, they #include the Gtk+ public header files and
link their application against the appropriate Gtk+ libraries.

What is a compatible ABI change?

If an API changes, it seems reasonable that the ABI also changes. A
compatible API change is one that does not require any changes to the
source code of applications using that API.

Example of compatible API changes include:

- adding a new declaration for a function, variable, struct or macro
- altering a constant to a different value (applications should not hard-code values for constants that are declared in include files)
- altering a macro or inline function definition, aside from changes in the number or type of any arguments
- moving some declarations from one header file to another one that is
also included
- adding new members to a struct or changing the order of struct members

Most other code changes to public header files result in an
incompatible API change which is also an incompatible ABI change.

Compatible API changes protect applications at the source level. A
compatible ABI change goes one better: it protects applications at the
binary level so that an already built application continues to work
against an updated shared library.

Some source-compatible API changes are incompatible at the ABI level.
Examples of incompatible ABI changes include:

- altering constants (const variables, enums or simple #defines)
- altering a macro or inline function, unless the original definitions would also work
- adding new members to a struct or changing the order of struct members
- altering the size of an any array that is declared in a public header file
- moving a function or data symbol from one library to another (unless the
  other library is linked to the first)

How does an API evolve without breaking application compatibility?

It is not always possible to evolve an API in an ABI-compatible way.
Sometimes it is necessary to change a struct, alter a constant, add a
parameter to a function or make some other change to the ABI.

As already mentioned, an API is implemented by one or more shared
libraries. By installing a set of shared libraries corresponding to the
existing ABI in addition to shared libraries with updated version
numbers for the new ABI, It is possible to evolve an API in a
compatible way.

Shared library version numbering scheme

Version numbers of shared libraries are a good way to communicate the
scope of the changes to each library. Version numbers have 3 levels;
for example libsample.so.1.2.3 has a major version number of 1, 
minor version number of 2 and a micro version number of 3.

Changing part of the version number communicates the amount of
change for this update to a shared library:

Micro - small bug-fixes, minor additions to an API
Minor - larger bug-fixes and ABI-compatible changes
Major - changes that break ABI-compatibility

If this scheme is followed, applications can link against the major
version number of a shared library, for example libsample.so.2.
It may not always be appropriate to do so; the following table
summarises how shared library version numbers may be used to
communicate the status of the interface supported by that library.

Stability    Release       Comments

Standard     Major (x.0)   Actual or de facto.
Stable       Major (x.0)   Incompatibilities are exceptional.
Evolving     Minor (x.y)   Migration  advice might accompany an
                           incompatibility.
Unstable     Minor (x.y)   Experimental or transitional:
                           incompatibilities are common.
Obsolete     Minor (x.y)   Deprecated  interface:  likely   to   be
                           removed in a future minor release.

Examples of these classifications in use would be:

- glib 2.0 - stable
- glib 1.3.1 - unstable
- libgnorba - obsolete
- libxml, libwww - standard (a public interface that the GNOME
                   Foundation does not own)