Re: platform compatibility policy

[Colm Smyth <Colm Smyth ireland sun com>]

Hi Maciej,

I'm very much in favour of a clear version compatibility policy.
I apologize in advance for what will be a longish mail on this
subject, I would welcome more discussion about this.

I'd like to clarify a point relating to public vs. private
interfaces and also to make some suggestions about the
differences beween source and binary-level compatability
and how to prevent accidental breaks to interfaces.


First of all, I believe that source and binary compatability 
should only be required for stable *public* interfaces.  

If an interface is wholly private to an application (e.g.  some
functions in a library that are shared by two closely related
programs, where those functions will never be needed elsewhere in
GNOME), then there is no need to maintain compatability over releases.

Also, if an interface is effectively an early-access technology
(say a brand-new library) but it is shipped with a major release of
GNOME (such as 2.0), it should not be required to be stable, but
anyone who uses that library needs to know that they are using
something that is rapidly evolving.

It would be really useful to attempt to capture GNOME's public
interfaces in a document, or (even better) a database. At
a high level, this should indicate the stability level of
each GNOME interface perhaps using names like stable, evolving,
unstable, obsolete, and standard to indicate how long that
interface will offer binary compatbility for any (client)
applications that use the interface.

Examples of these classifications would include:

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


Another aspect is how do maintainers and contributors to GNOME play
their part in keeping interfaces stable.  If maintainers ensure that
they have a small number of header files that define their public
interface, then they only have to watch these files to be sure that
code changes have not broken an API or ABI. There are also
some unwritten rules about public interfaces and how they
can be written so that source-level compatability is almost
the same as binary compatibility.

The difference between source and binary-level compatibility is
sometimes subtle. You could define source-level compatibility as
'my code compiles against the modules new header files'. Binary
compatibility involves a lot more:

- Provider-side:
  the public header files should not expose any internal
  symbols (data or functions); an example of this occurs
  occasionally in the X11 header files where a #define
  refers to a private symbol. Since the name of the #define
  is part of the public API, any change to the name of the
  internal symbol can be protected at the source level, but
  any code built against the header file will build in the
  name of the internal symbol - bad news.
  Macros in general have the potential to provide source-level
  compatability features that break binary compatability
  (e.g. #define PublicStringInterface(x) _private_sym[x].name
  will create a dependency not just on the name of the
  private symbol but also it's structure).
  
- Client-side:
  A user of a public interface is only binary compatible if
  the public header files contain no private symbols or
  structure references and if they use only the public interface
  
  Sometimes it seems convenient to use a private interface, for
  a number of possible reasons:
  - it's easier than writing the code yourself
  - there is no way to do it using only the public interface


It's possible to automatically validate an application
by checking that there are only references to public
symbols. By statically analyzing the dependent libraries
of an application, it's possible to find all symbols that
are defined within the application code and all symbols
that are imported from public interfaces in GNOME libraries.
Any symbol that is resolved from a GNOME library that is
not part of a public interface can be highlighted as
a binary compatibility violation.

Actually this is exactly that a Solaris ABI validation tool
called AppCert does. The hardest part is actually capturing
all of the symbols that are part of the public interface
of each library, although this too can be automated by
taking the syntax-checking parts of a C compiler and
outputting all symbols defined within the public header files
of a library into a 'database' file for that public interface.

If there is any interest in such a tool for GNOME, I can contact
the team at Sun responsible for AppCert to see if they
could contribute the AppCert tool-set to open-source
for use in the GNOME project.

Colm.


>Delivered-To: gnome-private-members gnome org
>Delivered-To: gnome-hackers gnome org
>X-Authentication-Warning: pythagoras.eazel.com: mjs set sender to 
mjs eazel com using -f
>To: gnome-hackers gnome org
>Subject: platform compatibility policy
>From: Maciej Stachowiak <mjs eazel com>
>User-Agent: Gnus/5.0802 (Gnus v5.8.2) Emacs/20.4
>MIME-Version: 1.0
>X-BeenThere: gnome-hackers gnome org
>X-Loop: gnome-hackers gnome org
>X-Mailman-Version: 2.0beta5
>List-Id: <gnome-hackers.gnome.org>
>X-BeenThere: gnome-private-members gnome org
>X-Loop: gnome-private-members gnome org
>
>
>Hey guys,
>
>As a coordinator for GNOME 1.4 I have found some slight lack of
>clarity about our platform compatibility policy, and how it affects
>releases.
>
>I would like to propose the following as a starting point for writing
>up a policy, coming to a consensus, and eventually having it adopted
>by the board. Like my proposed license policy, it's short and sweet.
>
>I'd appreciate people (especially Havoc who has worked hard on compat
>policy issues) would help fill in the holes.
>
>Regards,
>
>Maciej
>
>--------------------
>
>GNOME Platform Compatibility Policy (draft 1)
>
>1) Within major versions of the GNOME Platform, source and binary
>   compatibility will be maintained. Release coordinators shall 
reject
>   packages provided for a release if they break compatibility.
>
>2) There are, however, a few exceptions:
>
>   * Security issues that cannot be fixed without an API or ABI 
change
>     (although all due consideration should be given to adding new
>     APIs and deprecating the old ones, when possible).
>
>   * Major bugs (e.g. crashing) which cannot possibly be worked 
around
>     by apps
>
>   * Vote of the GNOME Foundation Board of Directors
>
>3) The Foundation Board shall declare what releases constitute a new
>   GNOME Platform version; at that time, source and binary
>   compatibility may be broken. [ note - GNOME 2.0 is currently
>   planned to constitute a new platform version ]
>
>
>
>_______________________________________________
>gnome-hackers mailing list
>gnome-hackers gnome org
>http://mail.gnome.org/mailman/listinfo/gnome-hackers
>
>


_______________________________________________
gnome-hackers mailing list
gnome-hackers gnome org
http://mail.gnome.org/mailman/listinfo/gnome-hackers