Re: First ideas

[Luis Villa <luis villa gmail com>]

On 11/18/05, Federico Mena Quintero <federico ximian com> wrote:
> On Fri, 2005-11-18 at 08:22 -0500, Luis Villa wrote:
> > More carrot, less stick?
>
> Why, that's exactly what I'm trying to figure out :)
>
> Let's ignore the fixed/total bugs ratio for now; that's a neurotic
> stats-taking thing of mine.  I'm sure it would produce interesting
> numbers.

I totally agree we should collect that information- I really want a
dashboard that collects lots of vital per-module stats: cvs commits
over time, bugs fixed over time, specific classes of bugs fixed over
time, # of open bugs, (mentions on planet.gnome? :) etc. But I'd like
to provide the information and see how it shapes behavior voluntarily
before requiring anything.

> About requiring documentation for libraries:
>
> The core GNOME hackers are not the audience for these docs.  They are
> good enough programmers that they can grok our libraries simply by
> looking at header files, or looking for examples of usage in the core
> GNOME programs themselves.
>
> The audicence for these docs is the average programmer, out there in the
> wild.
>
> If we want to achieve 10x10, we'll need GNOME to have apps that end
> users will want to use.  The only way to get these apps written is to
> make it possible for random developers to understand the GNOME platform.
>
> I'm afraid that there's not much of a carrot right now *for us*.  There
> is a carrot if you care about 10x10.  The only carrot would be to win in
> a competition upon gtk-doc's stats of "n% coverage" - that's meaningful
> for reference docs, not for tutorials, of course :)
>
> Also, I'll contend that the best person to write docs for an API is the
> person who wrote that API.
>
> And once you get into the habit of documenting your APIs, you see that
> yes, it takes a little effort, but it's not a big deal, either.
>
> During the early days of GNOME 2.x, we had a *hard* time getting used to
> the idea that the ABI/API couldn't change, just get additions.  In GNOME
> 1.x we were used to changing APIs all the time if they didn't do what we
> wanted.
>
> The early days of 2.x consisted of learning how to design better APIs in
> the first place, so that we wouldn't need to change them later.  Why do
> you think we have so many deprecable libraries right now?  Part of it is
> that their APIs suck, and part is that they also happen to be pretty
> under/un-documented.  They are the "there's only one person that
> understands this" kind of libraries.
>
> So, yes, I think at first we would have a mildly hard time getting used
> to the idea that we need to document our libraries.  In a year or two
> everyone would be used to it and they would just do it naturally.  Once
> we achieve that, you may see me pestering the release team to no-go on
> libraries which don't have unit tests ;)
>
> But one thing at a time, Pinky.

Two things:
1) this approach (gradually raise barriers until people are used to
is) arguably OK for existing maintainers, but it substantially raises
the barrier to entry for new maintainers, which is a problem.

2) the changes between 1.4 and 2.x didn't come because the release
team forced anyone to do anything- they came because leaders persuaded
and led by example. *After* that happened the r-t put in some (still
very mild rules) reflecting that consensus.

Luis