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

[Andrew Bennetts]

Thanks for the detailed feedback.  I hope you don't mind me replying to
just a small part that jumped out at me:

Neil Martinsen-Burrell wrote:
[...]
> 3.  Patch review for community members should be different than
> patch review for core developers.  The comments in a patch review
> may be enough to help a core developer fix the problem in the right
> way or if not, the core developers generally have enough confidence
> in the techniques that they use to mount a defense.  For casual,
> especially first-time nontrivial contributors, my experience is that
> these comments are often not sufficient to lead to an adequate
> resolution.

For what it's worth, I already try to do this when I do reviews.
Usually you can tell if the contributor is unsure about our coding
standards or how to use our test suite infrastructure, and for them I
will make sure I give pointers to relevant developer docs and APIs etc,
which an experienced dev won't need.  I will also invite them to ask
more questions for things they are still unsure about, and I do my best
to be responsive to those.

Sometimes I even volunteer to finish off a patch for someone if
they've run out of time or energy to get it in — but it tends to take a
while before I can get around to these (I have one of these queued up
for the moment...).

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.

> 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!

-Andrew.