Re: GNOME Namespace Management - ARC & GNOME

[Murray Cumming <murrayc murrayc com>]

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.

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.

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

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

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

[snip]

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

Thanks. That looks great. I'll read it all and respond if I have ideas.

[snip]

> 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?

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

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

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

>          11. Solaris package names
>          12. Java package names

Obviously not relevant.

>          13. Daemons
>          14. URLs

Do you have examples of interfaces and changes to them for these?

>          15. Windows EXEs, DLLs, VxDs, and registry IDs

I think you know that this is not relevant. 

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

I wonder how you test the "extra" interface types for breakage.
 
[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

>   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?

> 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?

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

Bear in mind, these are just my personal views.

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