GNOME.org
 

Re: GNOME Namespace Management - ARC & GNOME


Murray:


On Wed, 2004-12-15 at 15:14 -0600, Brian Cameron wrote:
[snip]


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. 

New APIs are well documented these days, particularly in GTK+. They've
developed a good culture of that.


Agreed.


However, GNOME tries to avoid blocking progress. We like great
documentation, but we'd find it difficult not to use new module versions
just they have less-than-perfect documentation. Personally, I like the
GTK+ way, but you have to be careful about messing with a process that
works so well.


I also agree that the GNOME process works well, and we shouldn't tinker
in it in ways that block progress.  Instead Sun would like to play more
of a role to improve the scale and quality of the GNOME documentation
so that the good work that GNOME is doing in terms of interface
stability is well documented.  Some minor changes in process might be
useful to consider, like better archival of interface discussion.


Working with the community to improve the interface documentation is a
way we can work on together to improve things for everyone.
Yes, bug reports and patches would be a very GNOME-compatible product of 
your ARC process. Luckily, it's not that difficult to write API
documentation patches.


Yes, this is my anticipation.  I would like to see Sun's internal ARC
process evolve into one where bug reports and patches are the way ARC
issues are brought to the attention of the GNOME community.


But there are some potential stumbling blocks.  For example, Sun's ARC
documentation is in Sun's documentation formats


Short examples of the visible output would be helpful here, on a website
ideally.


John Plocher and Ed Hunter are currently working to figure out what
internal ARC documentation is of most interest to the GNOME community.
Responding to Ed Hunter's emails on this topic is probably a good
way to help them clarify this.


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.


You have stuff, so you start. People will say what they like and what
they don't.

You would really help people how the process might have be applied to
previous GNOME changes. Hopefully that will show that your ARC would
often come up with the same decisions, where we worried about something,
while pointing out additional problems that should have been solved.


I don't think that the process would really be much different than the
process that the GNOME community currently follows.  The problem is that
interface change discussion happens in an ad-hoc fashion in multiple
places (on a dozen or so mail aliases, via CVS commits, IRC discussions,
etc.).  This means that people who aren't deeply involved with a given
module are often not aware of the specific changes.  If there were a
single mail alias that people cc:ed discussion about interface change,
then all of this information would be in one place and easy to review
in real time.  ARC isn't really interested in changing the process, they
just want to be more involved with the current process.  I think there
are some things the GNOME community could do to make it easier for more
people to engage in interface change discussion.


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



Is SPI your word for ABI?


SPI is a Service Provider Interface, an interface intended to be used by a
service instead of an application.


, both functions and header files)
         2. Command Line Utilities (applications or configuration or administration tools)
         3. Graphical User Interfaces (GUIs)
I think it would be best to forget this one. GNOME's UI is meant to 
improve, and it doesn't change without good reason.


I somewhat disagree.  I think the GNOME HIG is doing a good job of dealing with
issues in this area already, though.


         4. Character User Interfaces (CUIs)
Not relevant to GNOME. 


         5. Command line Interpreter languages


Probably also not relevant.


         6. Input/output file formats
         7. Resource & configuration file names and formats
         8. Databases


Not relevant, I think.


Depends a bit on your meaning of database.  Is the GConf configuration data
a database?




         9. Protocols or inter-component messages
        10. Log files




        11. Solaris package names
        12. Java package names


Obviously not relevant.


It might be expanded to rpm packaging, though these are perhaps more of an
issue for people who distribute GNOME.  However, having recommended rpm
naming suggestions might not be a bad idea.


        13. Daemons
        14. URLs
Do you have examples of interfaces and changes to them for these? 

Some GNOME programs depend on URL's to function, such as the gweather,
stock-ticker, and webeyes applets.  There are also places where URL's
are used in various programs.  These should not point to websites that
are unstable or that might be expected to go away.  If gtk-docs contain
URL's that point to the gtk-doc for a different module, this would be
an interface.  Those are some examples, I'm sure that there are
others.


        15. Windows EXEs, DLLs, VxDs, and registry IDs
I think you know that this is not relevant. 

Doesn't GTK+ work on Windows?  Though supporting GTK/GNOME as stable
interfaces on Windows might not be of highest priority.  I don't think
it is of interest to Sun, at any rate.


[snip]



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.


I keep hearing about some SUN ABI-checking tool, but it never seems to
appear.


Working on it.


I wonder how you test the "extra" interface types for breakage.


We don't.  We need to do a better job in this area in order to meet ARC
requirements.


[snip]



Sun's ARC prefers to review interface change proposals before or as
they are implemented.


Does this include interface additions? I fear that GNOME development
would slow to a halt if we had to ask a committee for approval every
time someone added a public function.

Deprecation-and-replacement happens less often, and at a more relaxed
speed. 
But you'd need to persuade individual maintainers to make use of this.
If your very nice, and it's useful and it doesn't get in the way, and if
they can choose to ignore you in the end, then it seems possible.

Maintainers already work with various freezes during the 6-monthly
release cycle, and ask for permission to break those freezes. It can get
difficult near the end of a cycle, but I think most maintainers find it
worthwhile. 
See "Creating a Schedule" here:
http://developer.gnome.org/dotplan/tasks.html


Yes, ARC wants to review interface additions.  However, I do not think
I'm suggesting any changes that would cause undue schedule blockage.  As
I mentioned above, I'm only suggesting that the GNOME community do a
better job of archiving change discussion.  Using a mail alias where
such discussion is cc:ed would be fine.  It might be good process to
make it a requirement that an interface change notification must be
sent to this alias as they are being made.  But that doesn't sound like
a great burden to the community process.  It would also be good if
the quality of the documentation at developer.gnome.org were improved
so that interface change were more clearly documented from
release-to-release.  I'm currently discussing ways we could improve
this area on the gtk-doc list.

I don't think it should be a requirement for such notifications to
require any sort of approval.  Instead, the list should only be used
to try and shoot down changes that are inappropriate, that might
break ABI, or to identify change that might require a library to
change its major version number.  It would also allow people to
verify that changes are happening in a sane fashion.  If a change
isn't completely sane, then people could use the list to discuss
better ways to meet the underlying requirements.


 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.


This makes sense to me.

[snip]


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.


You have to start somewhere. Why not put the documents online, so we can
start tearing them apart?


As I mentioned, Ed Hunter and John Plocher are working on this.


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. 

Why not? Have you asked the maintainers? Have they not responded?


Sun has been doing a poor job of ARC'ing GNOME so far and we have not
engaged the GNOME community well.  There have been a few occasions where
we have involved maintainers, and we have always found them to be helpful
and engaging.  Part of the problem is that Sun's ARC process is not well
designed to work with external groups, so we have been spending too much
time jumping through hoops and not enough time working to actually resolve
issues that ARC feels are important.  I've been working with ARC on this
problem and we have been making progress.  As I mentioned before, ARC is
now considering working more directly with the GNOME community to address
issues instead of following our internal process as we have.

So, this discussion has been helpful to assure ARC that the GNOME community
is serious and interested in finding ways to better document change.
The more we can make this work, then the easier it will be to shift
resources so that Sun employees spend less time jumping through ARC hoops
and instead spend more time working with the community to make things
better.


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 can't think of any reason, from GNOME's point of view, not to make
this existing stuff public.


Right.  Part of the problem is that ARC documents are internal and
proprietary to Sun.  We are working to change this aspect of the process
so that it is not required when Sun is working with external groups.
This is a bit of an experiment for Sun.

--

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