Re: Lowering the barrier (was: Re: build systems)

["Mikkel Kamstrup Erlandsen" <mikkel kamstrup gmail com>]

On 10/11/2007, Matteo Settenvini <matteo-ml member fsf org> wrote:

Il giorno ven, 09/11/2007 alle 16.58 -0600, Jonathon Jongsma ha scritto:
> On 11/9/07, Lucas Rocha <lucasr gnome org> wrote:
> > - Are the current drawbacks of using autotools in GNOME so so so
> > annoying that it would be really worth the effort of migrating to
> > something else?
>
> The only reason I could imagine migrating to something else at the
> moment would be if it lowered the barrier to contribution so that we
> got enough new contributors to offset the amount of work it required.
> I'm doubtful that this would actually happen though, and we'd need to
> be 100% sure that the system we were moving to was an improvement.
>

Changing subject since I think that the problem of lowering the barrier
of contribution is crucial to the success of any free software project.

I would like to discuss with you where we could act seriously in this
direction.

Good. I am greatly concerned by the alarmingly steep learning curve one has to endure to be able to contribute to Gnome (without resorting to Python/Mono).
 

I've got some comments to make:

* The GNOME love bugs weren't a bad idea, the only problem with some of
them was they were boring and you didn't learn a lot from fixing them.
For example, fixing include file order in headers isn't exactly what I'd
consider exciting if I were to hack on some part of GNOME. I want
action! Challenging ideas (but still, feasible ideas)! Furry little bugs
squashed! Anyway, I'd like to see more bugs marked with the gnome-love
keyword, and the most popular/new ones should deserve a window in the
wiki, updated every week for major visibility. Make it a challenge, let
the agonism arise between teenagers with too much testosterone!

* The first time I tried to write something with the GNOME stack of
libraries, I was baffled by ORBit. I simply wasn't able to get anything
clear out from its documentation. I even didn't understand exactly what
it was for. Three years, my first year as a CS student, and some beers
later, I stumbled upon the DBUS specification. It was clear, concise,
and explained very well to me what DBUS was for. After reading the
*DBUS* document, I started understanding *ORBit* (which is different,
obviously, but that gave me the insight). Following Murphy's law, now
ORBit is being put in a corner :-).
What I'm trying to say, is that we need some proper documentation
explaining how the GNOME stack is built, and what components fulfill
what need, bringing in concrete examples in the discussion. New hackers,
especially if young and inexperienced like me, really need this sort of
things to avoid going on a wrong path for months and then discovering
that what you wrote was already there. That discourages anyone to
continue.

* Proper API documentation is still more important. I think that having
100% symbols documentation should be a priority. I know that no-one
likes writing it, but it's necessary for all the people out there who
don't have the willingness to read the code. By the way, the Mono
library documentation is frankly quite incomplete. Also the Gtkmm one. I
know of at least three separate CS programming courses in C++ at
university that chose to use wxWidgets over Gtkmm just because of their
better documentation (I prefer Gtkmm, but I don't have a problem to
search also the Gtk+ docs as a fallback).

* Code a lot of times isn't commented enough. Also static functions in a
compilation unit should have at least a line explaining why they're
there and what they're about.

As you see, most of my problems go with the documentation, and not with
the code, which usually I find well written - at least, the code *I*
have read.

A more strict policy about API documentation would be good news, and
more abstract (vision, architectural) documentation 'd be wonderful
news.

I am not sure that enforcing stricter API doc guidelines is going to solve our problems. Here are the core issues as I see them

ISSUES:

 * GObjects are conceptually difficult when you have standard knowledge of C# or Java

 * Autotools are exceptionally hard to work with

 * Some parts of the Gnome API are just plain hard to use. Ever tried implementing a panle applet? Wonder why we have to many apps using tray icons?

 * General API docs are not as good as they could be. Compare QT4 documentation with GLib to see the point.

 * It is sometimes hard to grok how an application or lib is internally structured. While http://library.gnome.org/devel/platform-overview/stable/ goes some of the way describing the platform as a whole, the internal structure of apps and libs are sometimes elusive.


POINTS OF ACTION:

Here is a list of proposed actions to address some of the outlined issues. They are intended not impose excessive work load on module maintainers.

 * Write a "GObjects for Java/C# Developers" document (or maybe two separate docs) meticulously explaining the concepts of classes and object instances compared to Java/C# objects for the lay hacker

 * Generate UML diagrams and a short description of the module structure. Can gtk-doc generate UML? I think Anjuta can...

 * Make Anjuta better at GObject/Ginterface and Autotools handling. It is already good, but make it *excellent*

 * Encourage projects to include Anjuta project files

* Lobby for distributions to create a gnome-developer-studio package installing all build deps, documentation, latest anjuta, everything you need to hack on Gnome. Pimp those packages on the official Gnome pages.

Cheers,
Mikkel