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

[Andrew Bennetts]

Stephen J. Turnbull wrote:
> Andrew Bennetts writes:
[...]
>  > 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

It's true that some people will just want to fire and forget a patch.  However
my experience has been that many people (and perhaps most of them?  Citation
needed...) are happy to iterate a patch a few times with guidance.  Certainly
some people ask for help *before* they formally submit it, either to because
they need help to make the patch work at all, or because they are keen to make
sure they meet our acceptance criteria.  

I am happy for someone to say “here's a patch, but I don't have time to make it
any better”.  There's no guarantee that we'll accept it of course, but often it
will be, eventually, after someone else takes an interest and polishes and/or
champions it.

So there's a spectrum ranging from “I wrote something, here it is, I hope you
find it useful, bye” through to “I'm trying to fix this bug, I'm willing to put
practically unlimited time into this, can someone give me guidance when I get
stuck?”  I think we welcome contributions whereever they lie on this spectrum,
but perhaps we don't communicate this clearly, especially as we default to a
writing style in code reviews that implicitly expects a contributor to
follow-up.  And probably we do let too many of the incomplete contributions
languish longer than they should.

[...]
>  > > 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
>     ===================================

Thank you!

I think this would be a good addition to our documentation.  In the spirit of my
previous mail I'll even volunteer to turn this into a patch to do just that :)

(Obviously we lack a mentoring process at the moment, so I guess I'll comment
that part out for the moment.)

-Andrew.