Re: Suggestions for API/ABI Process

[Brian Cameron <Brian Cameron Sun COM>]

Mark:

Thanks for your comments.

>  - A lot of this reads like "you guys don't care about stability". In 
>    reality what you're proposing is to add more process, documentation 
>    and clarity around what we're already doing.
>
>    i.e. the community understands the need for interface stability, 
>    especially API/ABI stability, and has actually done a damn good job 
>    here since GNOME 2.0. Recall that the ABI audit Sun recently did on 
>    GConf, glib, pango, atk and gtk+ showed that the only "real" ABI 
>    change was Sun's own doing ...

I very much agree that the community has been doing a great job of
keeping interfaces stable, and I do try and highlight this in a number
of places through the document.  If there is anything specific that
you think is unfair in the document, it should be changed.  One of the
reasons the document is stored on the Wiki is so that other people in
the GNOME community can correct the wording where it is inappropriate,
provide links to resources that should be included, etc.

In pretty much every situation where the document is negative, I think
the issue has to do with documentation and process and not with
technical issues.

My hope is to work with the Release Team to define better terminology
and a better process so it is more clear to ISV's which GNOME interfaces
should be used when writing a GNOME application.

I argue that the current process is vague and provides ISV's with little
value.  The current API/ABI rules could easily be interpreted that all
GNOME interfaces are Stable.  This is potentially dangerous.  I think
many interfaces shipped with GNOME (such as libwnck, panel-applets,
libegg*) are not ABI stable and are not really intended for ISV use.
If you read the GNOME mail aliases thoroughly, you would probably know
this, but it isn't reasonable to expect ISV's to go through this
trouble.

I recommend that this be replaced by a system where the GNOME Release
Team defines what interface stability means, what is an interface, how
interface stability relates to library versioning, and how an ISV can
tell which interface is intended for their use.

>    You point out the libgnomeprint ABI breakage. Be aware that most in 
>    the community was unhappy about that, but even then (AFAIK) the 
>    maintainer did his best to make sure vendors could upgrade without 
>    breaking existing apps - he made it possible to parallel install
>    that version with the previous version, probably by following this
>    advice:
>
>      http://ometer.com/parallel.html

Right.  I very much agree that the community did a great job in this
situation, with one exception - documentation.  The Release Team process
should be improved so that such documentation oversights are less
likely to happen in the future.

When significant ABI change occurs in the desktop, especially change that
could affect an ISV, it seems reasonable to expect:

- That the GNOME release notes should highlight the issue and explain
  the reasoning for allowing the change.
- That the module documentation should make mention of the issue.

I would like to see the Release Team process evolve so that when such
issues are brought up in the mail discussions, a better effort is
made to include mention in the release notes and module documentation.

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.

>    The point is, that the community already cares about interface 
>    stability a lot more than you suggest in what you've written. This 
>    is a question of formalizing and improving what's already there. 
>    Expect people to get very defensive if they think this is "you guy 
>    suck, we'll show you how to do this properly"

As you say, the GNOME community already is doing pretty much all the
work.  What is needed is to take the best practices that are being
followed in the GNOME community and document them.  GNOME maintainers
should be encouraged to follow these "best practices".  Giving a
module a "Stable" classification, then, becomes a reward for doing
things the recommended way.

I'm suggesting that since the Release Team is responsible for GNOME
quality, that they should take responsibility for identifying which
"best practices" be used to ensure interface stability.

My intend with the document is to try and define a process that
encourages all GNOME modules to follow the best practices followed by
the most stable GNOME modules (glib, and GTK+).  I don't think I
am trying to say "we'll show you how to do this properly".  Instead
I am trying to say "Some modules in the GNOME stack are doing things
properly, let's make more of an effort to do things properly across
the board."

>  - We don't do things like "a declaration of stability from the module 
>    maintainer".

Okay, I'm not sure that "declaration of stability from the module
maintainer" is really a good description of the requirement.  All that
I am really saying is that an ISV should be able to look at the
module documentation and get an idea of which interfaces they can depend
upon.  The best way to do this would be for the Release Team to define
what is meant by Stable, and for the module documentation to reference
this definition.  This could be done by making use of the new gtk-doc
feature that allows each interface to be given an interface stability
level.  I've updated live.gnome.org to make this requirement more
clear, and hopefully less controversial.

>    The way things might happen is that the stability level
>    of stuff will be written down, discussed and changed until there is
>    broad consensus that it reflects reality.

In fact, I would argue that the process you are describing
already happens.  The way the community writes down, discusses, and
changes its interface stability information is via gtk-doc.  At some
point, the interfaces exposed in the gtk-docs should settle down to a
point where such "broad consensus" is possible.

I would argue that many modules have already reached this point.  glib
and GTK+ are examples.

>  - You have a column "Supported by Red Hat". I don't think that has any 
>    relevance and I'm not even sure what that actually means or where 
>    the information came from. I think its bogus, basically.

That section, along with the "Version Map" section are now removed from
the website.  I agree that the information for Red Hat wasn't official
and I don't think these tables really added much to the overall document.

>  - You're suggesting writing a lot of documentation. I'd suggest you 
>    figure out what documentation is really very important to this 
>    process and minimise it as much you can. Certainly don't make full 
>    API documentation a requirement for anything. People do want full
>    API documentation, but its a question of people having time.

I am not suggesting that full API documentation is required for a module
to be Stable.  Instead I am suggesting that the GNOME community establish
a rule that only interfaces documented in the gtk-docs and marked as
Stable should be considered for use by an ISV.  This seems reasonable.

If interfaces are not documented, then this simply means that the
GNOME community is not recommending that they be used.

Another idea is that the Release Team could identify a wider spectrum
of interface stability classifications that better reflect the way
things are done in GNOME.  Instead of just Stable/Unstable/Private,
there could be different grades of Stable.  Something like:

Stable+: Follows all best practices.  The module maintainers are
         committed to ensure that interfaces are well documented
         and it is clear to tell which interfaces are Stable.
Stable-: The GNOME community believes the interfaces in this module
         are Stable, but best practices are not followed.  So there
         are caveats.

In other words, we want to create a system where module maintainers
will naturally want to strive towards getting a higher Stability
classification to get their interfaces more widely adopted by ISV's.

>    i.e. don't demand work from people. Unless you're willing to do it 
>    yourself, of course :-)

Actually, I think most of the documentation is already written.  Most
modules that need to be considered Stable in order to write a
reasonable GNOME application already have pretty good interface
documentation.

However, there are some holes that should be addressed.  I'm happy to
do the work improving the documentation to meet requirements.  It
would be easier to do this if the GNOME Release Team were willing to
define the requirements for a module to be considered Stable, then
I could work to ensure that these requirements are met.

Brian