GNOME.org
 

Re: GNOME Namespace Management - ARC & GNOME


Murray:


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.


Good point.  However, I think it is also useful to explain a bit about
Sun's ARC process to the GNOME community.  Also, past efforts to try
to better integrate the Sun ARC and GNOME communities have not been
very successful, and I don't want to repeat past mistakes.

Part of this, I think, has been a general reluctance of the Sun GNOME
team to be seen as trying to impose any Sun-internal process onto a
free & public software project.  I certainly want to be careful that I
do not give this impression, and instead focus on issues that are of
common interest to both the Sun ARC and the GNOME communities.
Fortunately, many of the things that are of importance to ARC are
things like ensuring that a project has complete interface documentation.
Working with the community to improve the interface documentation is a
way we can work on together to improve things for everyone.

But there are some potential stumbling blocks.  For example, Sun's ARC
documentation is in Sun's documentation formats and (to date) has
covered only the specific GNOME releases that Sun ships on Solaris.
As you mention, Sun needs to be better engaged with the development
process going on in CVS head.  These are areas we can work together
and hopefully improve things, but we probably need some input from
the GNOME community about how to make this work.  This, perhaps, might
require coming up with documentation formats, process changes, and
interface taxonomies that make sense for the GNOME project.  If such
things were established, then I could write such documentation to the
GNOME public standard instead of sharing ARC documents with Sun's
jargon.


[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.


I'm glad to hear that, although I think it is also necessary for the
GNOME community to be involved with the process.  Some areas of the
desktop might be tricky to break down into stable and private interfaces
(thinking of the GConf key namespace for example).  I'm happy to put
together documents that highlight Sun's perspective of things, but
for such specifications to have meaning they will also need to be
formalized into specifications by the GNOME community as well.  I'm a
little unsure how this process will work, and would certainly appreciate
recommendations about how Sun should go about making such lists and
get the GNOME community to engage with them.


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?


Yes, the way Sun deals with this is to list all interfaces and label them.
I have been talking with the gtk-doc team about improvements that could be
made to gtk-doc to support such labelling, and you can read about it here
including information about the taxonomy that Sun uses:

  http://mail.gnome.org/archives/gtk-doc-list/2004-December/msg00008.html

Anyway, some interfaces can be marked Stable (public), Unstable, or Private.
Private interfaces are further broken down to specify if they are private
to a specific module, or private to a set of modules.  Read the linked
email (and the rest of the thread) to learn more.

Typically a library that tries to be ABI compatible is a mix of public and
private interfaces.  ABI only really applies to stable ones.  Yes, it is
common to have libraries whose interfaces are entirely private.

I realize that the GNOME community already does this to a degree (for
example, only public interfaces are included in gtk-docs).  However,
enhancing such documentation so it also covers interfaces such as
file formats, file locations, etc. are areas where the GNOME
documentation could improve.


+ 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.


That's good to hear.  Although interface stability extends beyond
binary compatibility issues.  Data file formats and file location
dependencies are examples of non-binary interfaces which can affect
product stability.

> This is our definition:

http://developer.gnome.org/dotplan/api_rules.htm

>

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.)


So, the current definition for the GNOME community is:

  Do not break ABI. For instance, if an application uses 2.6.0,
  installing 2.6.1 should not intentionally break that
  already-installed application.

Perhaps the definition would be improved by defining specifically the
meaning of interface.  It would be nice if it highlighted that for
a program to not break, non-binary interfaces also need to be
considered.  Here is the definition of interface that Sun ARC uses:

      The ARC definition of "interface" is broad -- any syntax or semantics
      that another project (or a human) could depend on. It is not limited
      to APIs nor limited to customer-visible project boundaries. Some common
      kinds of interfaces are:

         1. Libraries (APIs and SPIs, both functions and header files)
         2. Command Line Utilities (applications or configuration or administration tools)
         3. Graphical User Interfaces (GUIs)
         4. Character User Interfaces (CUIs)
         5. Command line Interpreter languages
         6. Input/output file formats
         7. Resource & configuration file names and formats
         8. Databases
         9. Protocols or inter-component messages
        10. Log files
        11. Solaris package names
        12. Java package names
        13. Daemons
        14. URLs
        15. Windows EXEs, DLLs, VxDs, and registry IDs

This definition may not apply cleanly to the GNOME community, but it might
help for the GNOME community to understand what ARC means by an interface.
It might also give ideas that would help to improve the GNOME community
definition.


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.


Yes.  Sun needs to be doing a much better job testing interface stability.
I am currently working with the SUN QA team to make this sort of testing
more of a priority.  It would also be nice if the GNOME community adopted
some better mechanisms for documenting change.  Currently it seems that
in order to get an accurate picture of change a person must keep a
careful eye on CVS commits and discussions going on in several dozen public
mail aliases.  While this information is public, it is hard to track down
or refer to.  As I mentioned above, I've been working with the gtk-doc
people to suggest ways that some of this information could be better
tracked in the gtk-docs.

Sun's ARC prefers to review interface change proposals before or as
they are implemented.  The ARC-chairs have told me that they would be
excited if the GNOME community set up a notification mechanism that
would highlight when changes to interfaces are planned or occurring.
If this were done, then they would be willing to review such changes
with an eye towards interface stability.  I suspect that other people
in the community would also find reviewing such emails useful.
Perhaps a separate mail alias where developers making changes to
GNOME interfaces would be expected to send an email describing the
planned change would help to keep such change-related information in
a single, referable place.  Since such discussions already happen on
various mail aliases, it would perhaps only mean that such emails
would need to cc: an additional list for archival purposes.  Taking
advantage of ARC's willingness to review interface changes might be
another way that problems or issues could be proactively identified.


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.


I hope so.  I sent out a document last week highlighting Sun's
perspective of the stability levels in the /usr/share, /var, /etc, and
$HOME directories and only received a single comment in response.
Breaking down the interfaces into Stable and Private is only meaningful
if the GNOME community helps to transform the list into a specification.
I am hoping that this document might inspire people in the community to
discuss ways that GNOME could better organize its files in these
directories.  Sharing ARC documents with the GNOME community is really
only useful if it helps to encourage discussion about how to make things
better.


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.


I'm happy to work more closely with ARC and the GNOME community 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.


Thinking more about this, I realize I should have more simply asked
how such ARC documents could help to create standards with the GNOME
community.  Simply sharing ARC documents with the desktop-devel-list
community doesn't, by itself, establish any standards.  Any ideas
would be helpful.


[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.


I agree that GNOME has done a great job of keeping GNOME ABI compatible.
However, I think that is only half of the battle.  In order for interface
stability to be meaningful, it also has to be well documented so that
users have a solid understanding of which interfaces they can depend upon.
This goes beyond library interfaces, which are currently well documented.
It also includes things like GConf key namespace, where things are more
murky and incorrect assumptions can easily be made.

I'm glad to hear that there is an interest in the community in working
together in this way.  I'm happy to work towards improving Sun's focus
so we can make the GNOME project even better.  But we also need your
focused help.  My job at Sun is to try and navigate the GNOME stack
through the Sun ARC process.  To date, we have spent much of our time trying
to hobble together the public documentation with the missing pieces.
Since this process has been internal, the documentation has tended to be
incomplete and with no real guarantee that the GNOME community agrees with
our understanding of what interfaces are Stable and what is Private.
Since we have only been going through this process for our Solaris GNOME
releases, our efforts have been focused on code considered frozen by
the community.  As you might expect, these problems have diminished
the benefits that Sun ARC reviews typically offer.

I have been working with the ARC chairs for a long time to get them to
the point that they finally agree that working to improve public
documentation and to test the code at CVS head is a better long-term
approach for Sun.  My hope is that the sort of documentation we need
to provide for ARC is also of use to the general GNOME community and
am interested in  finding ways we can work together to meet common
goals.  But in order for this approach to work, I need some help from
the GNOME community to help define better ways to document and
standardize the ways that GNOME uses its interfaces.  The ARC chairs
have also agreed to be more involved with reviewing the interface
changes going on within the GNOME community.  I think this is a
wonderful free resource that is being offered, but better mechanisms
for highlighting interface change within the GNOME community would
allow them to better focus their attention on this issue.

For example, some simple process changes geared towards improving
GNOME's change notification could really improve the ability of ARC
and GNOME to work together.

--

Brian
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]