Proposal: Change to library proposal process

[Gregory Collins]

On Wed, Jan 5, 2011 at 11:02 AM, Simon Marlow <marlowsd at gmail.com> wrote:
> And if we follow this discussion to its conclusion, we end up back where we
> started: modifying a wiki page is error prone and we need more automation,
> so we use the ticket system instead.
>
> I'm all for making the process more lightweight.  Why not just attach
> patches to the proposal email?  Updated proposals can be made with new
> patches attached.
>
> This mailing-list-only process would help address the concerns that the
> process is too much of a burden for the developers/maintainers themselves.
>  Someone with commit access need not create the ticket at all: they just
> make a proposal on the list, and as long as it isn't controversial they
> commit after the discussion period.  It's a small step from here to
> committing *before* the discussion, which is what some people want.  I don't
> feel strongly about that, as long as we have an established protocol for
> discussing changes to these core APIs.

The fact of the matter is that pushing patches to a mailing list is OK
but it's still a barrier to collaboration. Those of us who have spent
some time working with newer services like github or bitbucket will
attest that those models are clearly superior for a variety of
reasons. When someone wants to make a patch for our project, they fork
our repository on github, code their patch, push it to their forked
repository, and send us a pull request. Every member of our "core
team" gets a message in our inboxes and any one of us can apply the
patches with a couple of keystrokes.

If I have reservations or would like to see changes, sometimes I send
the patch back with comments, it gets changed in the submitter's
repository, I get another pull request, and I apply it. 95% of the
time, however, I apply the patch without modification or I write my
own cleanup patch. If someone takes the time to do a bunch of free
work for our project, unless the patch is really questionable or
potentially controversial, my default posture is to happily accept it
and make the changes I would like to see rather than forcing the nice
contributor to jump through a bunch of hoops to make the patch perfect
before I deign to accept it.

A couple of philosophical principles which I believe should apply here:

  * it is better to ask forgiveness than to get permission

  * it is better to avoid tedious discussion even if it means taking 2
steps forward and 1 step back sometimes. Rolling back a controversial
patch is an O(1) operation.

  * pull scales better than push

  * inertia should favour those who want to make forward progress
rather than those who would like to slow it down: i.e. it should be
easier to get a patch through the process than it should be to slow it
down

  * code should speak louder than email on mailing lists.

My dream scenario for these libraries would be the following:

  * The code repositories living on github, managed by a "haskell"
organization to which a core group of contributors has commit access.
This organization should not be very exclusive: the barrier to gaining
commit access should be low, i.e. "prove you're not a muppet and ask".
"Git isn't darcs" but speaking as someone who has tried most of the
various options which are available, the tooling on github is *easily*
an order of magnitude better than anything else which is available.

  * Code and API quality are ensured through a branching/release model
rather than through extensive weeks-long patch review. Make a mess,
clean it up, wash, rinse, repeat. Experienced contributors,
maintainers, or "key stakeholders" get to exercise their gatekeeper
roles by having sign-off authority for releases.

  * Code review outside of the core team is accomplished by the fact
that someone with commit access needs to apply your patch. For
no-brainers discussion would not be necessary, in other cases mailing
list discussion might be appropriate. The criterion for accepting
changes should not be "is this perfect?" but "is this a net
improvement from what we have now?"

  * Code review inside the core team is accomplished post-hoc. Any
reasonably modern code hosting service can be configured to spam a
mailing list with patch notifications or will have an RSS feed you can
subscribe to. Remember: rolling back a patch is O(1), and if a patch
takes O(n) effort to make, fixing it is usually O(n/k), 2 <= k <= 10.

  * As a social contract, potentially contentious patches (big
re-orgs, breaking changes, etc) should be posted for discussion and
advice. The mailing list, however, should not be used for gatekeeping,
*especially* not in a consensus model. If an issue is controversial,
after a certain amount of discussion anyone on the core team should be
able to call for an up-and-down vote. People who want to propose an
alternative should come armed with code. A big plus for "social code"
services like github is that the barrier to this kind of
experimentation is O(1).

Ian had some criticism for me in our IRC discussion about this issue
yesterday, saying: "Have you failed to get a change in you think
should have got in?" The fact of the matter is, I would definitely
like to contribute but I'm not going near our current process with a
20-foot barge pole. And I'm unequivocally not the only potential
contributor who feels this way. From an interested observer's
perspective, it seems like libraries@ is where good code goes to die,
and I don't have the time, energy, or patience to endure it.

Cheers,
G
-- 
Gregory Collins <greg at gregorycollins.net>