Re: Suggestions for API/ABI Process

[Brian Cameron <Brian Cameron Sun COM>]

Murray/Others:

Ah, sorry, I know I can get runaway at the mouth.  I'll try to be more
to-the-point.

> > I argue that the current process is vague and provides ISV's with little
> > value.
>
> I agree that it would be nice to clearly identify everything. With your
> help, we are getting there.

Yay!

> >  The current API/ABI rules could easily be interpreted that all
> > GNOME interfaces are Stable.
>
> However, I don't think that extreme is likely. There's a fairly clear
> separationg between Platform and Desktop.

Ah, I didn't realize that the API/ABI rules were different between
Platform and Desktop interfaces.  This should be documented in the
API/ABI rules more clearly.

>>> Also, I think it should be expected that when an interface changes in
>>> an incompatible way, this should be reflected in the library versioning.
>>> Looking at libgnomeprint 2.0 and 2.2, one might think that they should
>>> be ABI compatible since it seems only the minor number changed.  In
>>> the libgnomeprint example, they added a "-2" to the end of the library
>>> name.  The glib/GTK+ libraries never use such a suffix to indicate ABI
>>> change, instead they always bump the major version number.  It seems
>>> like different modules are doing things in ad-hoc ways.  What is
>>> the best pratice here that GNOME libraries should be following?  I
>>> think the Release Team should define this.
>
> Why does it matter? What is the advantage? Is it worth losing the
> advantage of most GNOME 2 libraries being 2.something?
>
> libgtk-1.2.so is clearly different to libgtk-2.0.so and
> libgnomprint-2.so is clearly different to libgnomeprint-2.2.so
>
> No massaging of those numbers, other than having the same names, will
> make those libraries ABI compatible. They are different libraries.

It matters for the following reasons:

1) There should be clear rules for how libraries should "rename"
   themselves when ABI incompatible interfaces are introduced.  The
   libgtk example is a better naming mechanism because the version
   change of 1.2 to 2.0 more clearly highlights an ABI difference.
   libgnomeprint change from 2 to 2.2 seems to indicate a minor
   release.

   It isn't necessarily bad if different libraries are following
   different rules.  But if they are, the following needs to be
   better documented:  what the different rules are, how to tell which
   libraries are following which rule, and how to tell when an ABI
   incompatible difference is added to the library by looking at its
   version number.

2) In order for GNOME's API/ABI policy to be meaningful, Stable
   libraries should not change ABI in the GNOME 2.x timeframe.
   So, either libgnomeprint* isn't Stable ABI that people should
   use, or GNOME should have been bumped to 3.0, or this ABI
   change was a mess-up that we should learn from and avoid in the
   future?

   If the answer is libgnomeprint* isn't Stable because it is not a
   part of the Platform interfaces, then this might not be a great
   answer.  It's hard to imagine that ISV's won't want access to
   the library that gives programs access to printing.  Do libraries
   migrate from Desktop to Platform when the GNOME community
   recognizes that ISV's might need to use the library?

In other words, I'm not trying to suggest that anything is wrong
or broken.  I think the main problem is that the processes are not
documented, so the situation seems confusing.  And this makes it
look, in my opinion, like we're not doing a great job when we really
are.  Perhaps things like how API/ABI rules change between desktop
and platform interfaces is clear to some people in the GNOME
community, but how can the general public (including ISV's) know
the difference if it isn't documented clearly?

> Brian, may I edit http://live.gnome.org/InterfaceSpecification for
> brevity? You might want to keep a copy of the original in case you don't
> like the result.

Please update it.  It is on live.gnome.org so it can be a living
document that best reflects the way the GNOME community views interface
stability on the desktop.

Brian