Re: commandline interfaces

[Brian Cameron <Brian Cameron Sun COM>]

I think when interfaces are highlighted as needing higher interface 
stability, but
don't fall neatly into the current API/ABI Desktop/Platform rules, that the
module maintainer should be encouraged (at least) or required to document
the interface stability issue in the manpage or other module documentation.

That's the under 10-line version of my thoughts for those like Jeff.  
For those
of you who want to dig into this topic more, you can read on...

In the past, I have discussed this topic - that there is a need for 
stronger stability
definitions for non-library interfaces covered by the GNOME API/ABI Platform
Library policy:  http://live.gnome.org/ReleasePlanning/ModuleRequirements

As the maintainer of GDM, which is another program whose command line
and configuration format have a need for stability requirements.  Users 
don't want their
prior GDM configuration to break on upgrade, obviously.  However, GDM is
considered a part of the GNOME "desktop" not the "platform", so there is
no clear GNOME-wide standard for how such interfaces should be 
maintained, or
to describe how module maintainers should work together to ensure 
interfaces
don't break.  The current process is more reactive, where solutions are 
found
(hopefully) after breakage is noticed.  Unfortunately this process 
doesn't encourage
module maintainers to document module dependencies and therefore perform
more reasonable sanity tests for their modules.

For example, I'm well aware that the fast-user-switch applet depends on GDM
interfaces, but this email reminded me that the GDM module documentation
should probably highlight this fact - perhaps it would remind me to be 
better
about testing it when I make GDM changes.

Therefore, starting with the GDM 2.14 release, the module documentation 
identifies
which interfaces user can rely upon.  Note section 2.2.

http://www.gnome.org/projects/gdm/docs/2.14/overview.html

I would recommend working with the bug-buddy maintainer to document such
stability issues and promises in the bug-buddy man page.  Since there is no
GNOME-wide process for defining how this should work, the process is
currently up to the module maintainers and a bit ad hoc.  But I think man
pages would be a reasonable place where users expect to look to find
such information.

There has been improvement in stability with recent requirements for the API
documentation to be more carefully maintained,  but progress seems to be a
bit slow going.  I think it is just hard for a large diverse community 
to react
more quickly.  But it's a good topic to discuss and think about, I 
think.  The
GNOME desktop would certainly benefit if those who want to integrate with
it have more clear information about what interfaces they can depend upon.

Brian
.

> (I'm in ranting mood today...)
>
> So, another thing I noticed while doing rawhide testing is 
> that the bug-buddy commandline interface got broken in 2.15.
>
> As a consequence, evo can no longer bring up bug-buddy to report
> a bug, and ironically, the .desktop file shipping with bug-buddy
> itself got broken too. (see
> http://bugzilla.gnome.org/show_bug.cgi?id=346901)
>
> Maybe it is worthwhile to remind everybody that commandline
> options establish an interface too, and that it needs to
> be preserved just like the API. Command lines get stored
> in saved sessions, in .desktop files, in g_spawn() calls
> deep in the code...
>
> Matthias
>
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/desktop-devel-list
>