Defining specific problems and handwaving at solutions (was Re: What's Canonical thinking about Bazaar?)

Stephen J. Turnbull stephen at xemacs.org
Wed Nov 11 05:15:58 GMT 2009


Andrew Bennetts writes:
 > Neil Martinsen-Burrell wrote:
 > [...]
 > > 3.  Patch review for community members should be different than
 > > patch review for core developers.

[snip - some context may be lost, don't take this as representative of
Andrew's opinion!]

 > I'm sure we can do better.  For example I'm sure our docs about how to
 > write code to contribute to bzrlib, especially about how to use our test
 > suite, could do with a lot more elaboration.  Maybe there's a way we can
 > make it clearer that code review is a conversation, not a one-off final
 > judgement, and it's perfectly ok to have several rounds of questions to
 > clarify what's needed.

No, in many cases that would just inhibit the initial contribution,
rather than having it abandoned after one round.  The problem is that
the contribution as initially submitted usually is a pretty complete
answer to the *submitter's* question(s).  They're not interested in
answering more questions or having a conversation.  They're interested
in serving other people with the *same* or similar questions and
getting back to their own work quickly.  See also point 5.

What's needed is to streamline the process and give non-committer
contributors more support.  One approach I've seen proposed is taken
from Heinlein's "Starship Troopers": reviewers aren't allowed to
submit patches, submitters don't have a vote.  It's easy to see why
this would work well[1]; it's also easy to see why it will never be
implemented in an organization where developers have any say. :-)

 > > 5.  HACKING.txt is good but it is very, very large and hard for a
 > > casual contributor to work through and ensure that their submission
 > > meets the widely-scattered guidelines.  We've got "Bazaar in Five
 > > Minutes", why not "Bazaar Contribution in Five Minutes".  I would be
 > > willing to work on such a document if people were interested.
 > 
 > I'm definitely interested!

Sad to say, without a change in process, "Bazaar Contribution in Five
Minutes" is an oxymoron.  Nevertheless, here's one draft:

------------------------------------------------------------------------
    Bazaar Contribution in Five Minutes
    ===================================

    Contributing to Bazaar requires attention to quality.  To ensure
    high-quality commits, the "Bazaar process" involves you in our
    code review and improvement activities.

    In brief, a contribution should include:

    1.  A brief rationale, including expected audience and use cases,
        for inclusion in Bazaar.

    2.  A branch registered as a branch on LaunchPad, and submitted as
        a merge proposal.

    3.  The branch should include:

        a.  implementation of the feature,

        b.  user documentation (if the feature is visible in the user
            interface) and/or developer documentation (if new or
            changed APIs are provided), and

        c.  tests to ensure the specification is correctly
            implemented.

    For more information, see HACKING.txt.

    If you are not an experienced Bazaar contributor, why not take
    advantage of our Bazaar Mentors Program?  When you submit your
    merge proposal on Launchpad, simply tick the "I'd like to be
    mentored, please" checkbox.  Or you can ask on the Bazaar Mentors
    Forum.  Please read the Bazaar Mentors FAQ, first.

    Current Bazaar Mentors (as of 2009/11/11)
    =========================================

    None.  How about you?<wink>

    Bazaar Mentors FAQ
    ==================

    1.  Why is this "Bazaar process" in HACKING.txt so complicated?

        Answer: If we knew /that/, we'd simplify it!  We are working
        on streamlining many aspects, but quality comes first.

------------------------------------------------------------------------

I hereby place the above document in the public domain.

The FAQ can grow as needed (but should not duplicate anything in
HACKING.txt), and the mentors list will hopefully grow without
bound.<wink>  The main document should not get any longer.  Perhaps
HACKING.txt could be reorganized to fit the schema above.

Note that mentors should get official support.  Successful mentors
should be given Mentor-of-the-Month awards, some sort of financial or
work-release incentives should be considered, the number of mentored
contributions should be reported regularly, and if the rate of
mentoring drops, consideration should be given to increasing
incentives.


Footnotes: 
[1]  See also Fred Brooks's description of the "surgical team" in *The
Mythical Man-Month*.




More information about the bazaar mailing list