Re: Suggestions for API/ABI Process

[Brian Cameron <Brian Cameron Sun COM>]

Since there is some discussion going on desktop-devel-list about how
an improved API/ABI process could work, I thought I would explore
what I think this could work best.

For the simple reason that the GNOME stack should more clearly
identify which interfaces are intended for ISV use (or Stable)
should clearly identify themselves to the ISV audience as being
for their use.

This could be done by including a paragraph in the module README,
or perhaps a new STABILITY file which states something like "I am
a Stable module, the interface documentation included in this
module highlights those intended for ISV use." and contains links to
the module interface documentation and to the GNOME Release Team
website which contains good definitions of what Stability means
to the GNOME community.  The website would include a list of
reasonable expectations required for a module to be ready for ISV
use.  This way ISV's are sent a clear message about what Stability
means, and which interfaces they should consider using.

I think the expectations that are being suggested are reasonable
requirements for a module to be "blessed" for ISV use:

+ the interfaces should be of interest to ISV's.
+ interfaces should be following the current API/ABI standards as
  posted on the Release Team website already.
+ interfaces intended for ISV use should be documented
+ changes to interfaces from release-to-release should be included
  in the documentation
+ library versioning should follow a reasonable standard.

The intent is not to impose draconian rules on a set of GNOME modules,
but to reward module maintainers that are doing things correctly with
more public recognition of their efforts.  Certain modules (such as
glib or GTK+) could be given such recognition today.  The Release
Team could consider giving different grades of recommendation.
Perhaps if a module conforms to all expectations it is given a
better recommendation than a module that conforms to just some
expectations.

I think it would be a reasonable expectation that all GNOME Platform
modules should fit into this Stable category, though this wouldn't
need to be a requirement.  Perhaps instead something to strive for.
It might be useful for the Release Team to make these expectations
a requirement for new modules wishing to become a part of the
Platform.

This would be useful because it defines a clear roadmap of how a
module should evolve to be a part of the Platform intended for ISV
use.  This would encourage ISV's to get more involved.  If an ISV
needs to use a particular interface that is not in the Platform,
and sees that the only issue is documentation bugs, the ISV could
work with the GNOME community to help improve the situation so the
module can be given a Stable label.  This would be of particular
interest to Sun, since Sun wants its customers to make use of the
GNOME interfaces, but is unsure which ones to recommend to its
customers.  It would obviously be better if the GNOME community
could make it more clear which libraries are intended for use
for all GNOME users (rather than Sun trying to define this just
for Sun GNOME users).  If the  GNOME community can help to
establish reasonable expectations, Sun would be delighted to help
ensure that interfaces needed by ISV's have a Stable for ISV
use classification.

It would probably be useful if the GNOME Release Team website
include a 3-dimensional matrix which listed each module, each
GNOME release, and each expectation.  The matrix could highlight
how well each GNOME module conforms to the expectations from
release-to-release.  Assuming we can establish a reasonable set
of expectations, I would be happy to do the research and fill out
such a matrix.  I would file bugs discovered in the research
and work to correct these bugs, so that all Platform modules
conform to the expectaitons.  Further I would be willing to
improve the documentation for Desktop libraries that would be
useful to ISV's so they meet the expectations and can be
considered for inclusion in the Platform.

I don't think that the Release Team process should be responsible
for reviewing compliance to the expectations.  Documentation issues,
in Platform libraries when discovered, should be treated as bugs.
They perhaps should be assigned a high priority.  It should be the
responsibility of the module maintainers to agree to follow a
reasonable set of rules.  We shouldn't add burdensome process to
the Release Team.  Instead the Release Team should just be clear
about "what it means to be a Platform module intended for ISV
use".  Modules that wish to be used by ISV's will then understand
what they need to do to fit in this category, so they should
know the process of how to get into this category.

In fact, I'd argue that the GNOME community is very close to being
able to give all Platform libraries such a Stable classification.
The GNOME community already does a great job of keeping API/ABI
stable.  There are a few minor documentation issues, which I'd
argue mostly exist because module maintainers aren't following
a consistant list of expectations.  I don't think fixing these
issues is a great deal of work.  We are in the middle of doing
the "harder" task of defining what message the GNOME community
wants to send to ISV's, and how to communicate that message.
Once we get past this hurdle, putting the finishing touches on
a good ISV story will be straightforward.

Brian