Re: First ideas

[Elijah Newren <newren gmail com>]

On 11/17/05, Federico Mena Quintero <federico ximian com> wrote:
> I'm spinning this off the thread we had, since I now have more concrete
> ideas :)
>
> 1. Have a deadline for API docs.  Just like we don't accept API/ABI
> breakage, I'd like us not to accept cases where libraries introduce new
> APIs without documentation.  I saw the TwoPointThirteen calendar and
> there's this:
>
>         Jan 16 - API freeze, 2.13.5 tarballs due
>         Jan 30 - 2.14.0 beta1 tarballs due, UI freeze
>
> Could we add something in between like this:
>
>         Jan 23 - API documentation deadline.  If you added new APIs
>         to a platform library, they must have docs or we nag you endlessly.

To do this, we'd need to get community consensus that it's okay. 
Murray tried to bring this up just a few months ago; see
http://mail.gnome.org/archives/desktop-devel-list/2005-August/msg00003.html.
 Brian and I were supportive.  There was fairly strong resistance from
Luis and Mark.  Matthias had a question about how it'd work.  All in
all, not a real huge response rate, and since Mark was the only
maintainer of a platform module out of the group that responded, it
seemed to kill it for the time being.

I'd love to see it picked up again.  The main work involved is getting
the community to agree to it.  If they won't do so, the appropriate
route is to somehow get work going on documentation separately so that
we can start addressing any concerns and hopefully allow us to bring
it up again later.

> In particular, we sometimes add non-code interfaces like public GConf
> keys (which are invariably undocumented), which other people rely on
> eventually and yet we make no commitment to them.

We'd have to be careful to specify that we mean this too if we want it
documented.  It may increase the amount of resistance, though.

> 2. In each module's release notes, have a list of newly-added APIs.  You
> can see that (1) and (2) are sort of tied together; if (1) happens, (2)
> is nearly effortless.

Each platform modules release notes, yes?  Do all the modules even
have a real set of release notes?

Again, though, it'd have to be a community consensus thing.  We need
someone (like you) to go out and build up that consensus.

> 3. Let's keep track of modules whose fixed/total bugs ratio didn't
> increase during each release.  I'm not sure how this will work for
> Special(tm) modules like GTK+ which have a million API requests, but
> people don't ever follow up on them --- maybe GTK+ just needs to make a
> decision and WONTFIX them after some time unless the reporters care
> enough to implement the stuff themselves.

We can keep track of it.  What are we going to do with the ratios,
though?  Send out statistics to d-d-l?  I'm kind of leery of the idea,
though, as bug counts often tend to be more proportional to module use
and visibility than they are to bugginess.  But I'm willing to be
proved wrong and it probably can't hurt to just start tracking it.

> 4. dotplan and ReleasePlanning are more or less the same thing.  Can we
> deprecate dotplan and just redirect it to ReleasePlanning?  Any missing
> sublinks from dotplan should get moved to the wiki.

It basically is deprecated and the plan for some time has been to move
it over to the wiki.  It just hasn't been done yet.  Anyone on the
team ought to feel free to work on it and send the rest of us an
occasional update after any big changes.

> 5. We have talked about this in the past but have not formed concrete
> plans.  Sometimes we find things that should be improved or made
> consistent across the whole desktop --- a magic new API that solves a
> problem for everyone, a consistent mis-use of some clipboard type, etc.
> How can we get people to know about this information, and have them fix
> things on time?  Is it just an organizational issue?

Yeah.  Usually it's just an individual or small group that attacks it,
files bugs and patches, and then follows up on all of them.  Kjartan's
really good at this kind of thing.  I really don't know any better way
to do it, but I'm all ears.

> I'd really like to nail (1), (2), and (4) for the 2.14 release.
> Thoughts?

That'd be awesome.  I'll be behind you cheering you on.  ;-)

Cheers,
Elijah