Re: GNOME Namespace Management - ARC & GNOME

["Murray Cumming" <murrayc murrayc com>]

[snip]

> Sorry that my emails are so long, I
> hope they aren't putting you to sleep.  :)

You could make them shorter just by answering direct questions. Please do
try to be concise and self-editing.  Just give us a URL to previous stuff
in the archive instead of repeating yourself. Personally, I want this to
succeed, and I think that brevity and clarity are how to do it.

[snip stuff about ARC]

> In order for a project to be acceptable to ARC, it is necessary
> for all public interfaces to be documented and that all changes
> to public interfaces be clearly documented from release-to-release
> with potential breakages highlighted.

Sounds good.

>  The documentation that the
> GNOME community provides via gtk-doc provides us with some of
> this needed information, but is lacking in some areas:
>
> + Current gtk-docs do a good job of documenting library
>    function interfaces, data structures, enumerations,
>    and macros - but currently do not document how the code
>    interacts with the file system or environment variables
>    which ARC consideres interfaces of equal importance.
[snip]
> + ARC considers data files that users or sysadmins might be
>    expected to edit or integrate with to be interfaces.  Examples
>    would include the gconf database, gtkrc files, theme files,
>    etc.  Many of these interfaces are not publicly documented,
>    and have no stability guarantees from the GNOME community.
>    For example, ARC would like to see that the GNOME gconf key
>    namespace be documented publically with some indication
>    about what keys are stable, and which keys are supported
>    from release-to-release.
>
> + The GNOME community does not seem to publicly highlight
>    what parts of the GNOME stack are considered stable.  There
>    does not seem to be an official breakdown of the interfaces
>    that clearly states "these interfaces are guaranteed to work
>    until GNOME 3.0, these interfaces might change before then,
>    these interfaces should be avoided if you want stability
>    from release-to-release, etc.

The libraries in the GNOME Developer Platform offer ABI stability. That's
why it's called a developer platform.

Some parts of those libraries are not public API, such as the gconf CORBA
API. I'm sure we would have no objection to SUN making a list of these
things.

However, do you accept the idea that a platform library may have a part of
its API that is not public and ABI-stable, such as some small parts of
GTK+? And do you accept the idea that an application may consist of
libraries whose whole APIs are not public, such as GNOME Desktop modules?

> + It seems that the GNOME community's definition of ABI
>    compatibile means something like "you can recompile your
>    code with the new libraries and it will work".

No, that's completely false. We are talking about ABI, not just API. This
is our definition:
http://developer.gnome.org/dotplan/api_rules.html

There are also rules for the Bindings, which may
break-and-parallel-install more often, if the programming language demands
that:
http://developer.gnome.org/dotplan/bindings/rules.html

(I'm sure we'd welcome a more formal/improved definition. The GNOME Board
(Jody, I think) was orginally working with people from SUN to get one, but
they didn't succeed, so Imade that one.)

>  Sun's idea
>    of ABI compatible means something more like "you can take
>    a GNOME 2.0 application package/rpm and install it on a
>    system with GNOME 2.6 and it will work.

That's the promise that we make about the Developer Platform. That's been
fairly successful. Where it's not, a fuss should be made, ideally during
the development cycle.

By the way, I _believe_ that JDS always tracks the previous GNOME release.
Maybe the SUN developers would catch problems quicker if they synchronized
with our release schedule, during which problems can be identified and
dealt with.

>  In other words, if
>    the application depends on GConf keys provided by the desktop
>    they will still be supported, if the application installs
>    mime-files/themes/icons/etc. that are intended to integrate
>    the application into the desktop the integration will still
>    work reasonably, etc.

I love the idea of identifying the public parts of these "extra ABIs". I'm
sure that the community will support and help any SUN effort to do that.

> What we have been doing to date has been to take the public
> gtk-docs and add the missing pieces to create internal documents
> for ARC review.  As you can imagine, it is very time consuming.
> To start somewhere, we are starting at the bottom of the stack
> and going through a proper ARC review process for the lowest
> level libraries (glib, pango, gtk) with the hope that over time
> we will expand this list so that more of the stack goes through
> complete ARC review.  Obviously, few GNOME programs only depend
> on glib, pango, and gtk so we need to make quite a bit of ground
> before Sun will feel comfortable supporting the average GNOME
> program, or suggesting that Sun customers consider using the
> GNOME development stack to write their own applications.
>
> In bringing these issues up with the GNOME community, my
> hope is that the community will also agree that issues of
> stability are generally important to all GNOME users and
> might be interested in working with Sun to provide better
> public documentation that would also better meet ARC
> requirements.  This would make it easier to get more of
> the GNOME stack through the ARC process and would mean than
> GNOME could be better supported by Sun.  It would also mean
> that Sun's ARC community would be reviewing more complete and
> accurate documentation and would be better able to send
> useful comments back to the GNOME community.
>
> Since the sort of information that ARC requires is typically
> of general interest to developers, I suspect that working
> towards improving GNOME's developer documentation would also
> be of use to the general GNOME community.  If people looking at
> developer.gnome.org could see from the documentation that
> GNOME takes interface stability very seriously, this could
> easily encourage more people to consider GNOME as the right
> desktop to integrate with.
>
> I also think that the GNOME community would benefit from more
> discussion about how it uses its interfaces.  As an experiment
> to see if ARC-related issues are of use to the community, I
> have brought up the topic of how GNOME makes use of file
> system interfaces in the /var, /etc, /usr/share, and $HOME
> directories.  I think that GNOME could benefit from thinking
> about such interfaces and how to best organize things to
> ensure ongoing stability from release-to-release.

Sounds wonderful. These things need somebody, such as SUN, to drive them.

> If the community is agreeable, I would like to continue
> sharing information about Sun's internal ARC process when it
> relates to the GNOME project.

I don't think anybody could have any objection. You don't need to ask to
ask. It sounds good to me.

[snip]

>  >>> One thing that makes GNOME a little easier to deal with is that
>  >>> most Sun customers do not build their own applications using the
>  >>> GTK+/GNOME stack.  Further, Sun discourages customers from
>  >>> depending on (linking against, for example) the GTK+/GNOME stack
>  >>> since the GNOME community doesn't provide strong enough stability
>  >>> guarantees.
>  >>
>  >>
>  >> That's a shame but understandable.
>  >
>  > No, it's a vague statement, which is even contradicted later when he
> says
>  > that SUN do in fact recommend GTK+ and libglade. It's important to be
>  > precise. Maybe we are talking about libraries that are not part of
> GNOME
>  > or not part of the GNOME Developer Platform.
>
> Actually Sun supports the entire GNOME stack, and if a customer makes
> use of GNOME interfaces Sun is obligated to support them.  However, Sun
> discourages users from using interfaces outside of glib, pango and gtk+
> since they do not have sufficient public documentation to go through
> a full ARC review.  I hope I have made this more clear.

[snip]

> Actually ARC has been very pleased with the library stability found
> within GNOME, especially in low level libraries such as glib, pango, and
> GTK+.  Sun is more worried about the stability of interfaces higher in
> the stack, like bonobo, libgnome*, gconf, etc.

So, in summary, you meant GNOME, not GTK+, or "GTK+/GNOME". And you have
not identified any "simple library ABI" problems in the public API in the
GNOME Developer Platform. There are many things that GNOME gets inredibly
right about ABI, so let's not start by ignoring the hard work that goes
into maintaining that commitment.

I think we need your focused help to make it even better.

Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com