Short, task-based bzr doclets for real-world use cases.

[Stephen J. Turnbull]

Karl Fogel writes:

 > Then perhaps we shouldn't present the regular contributor scenario
 > at all, at least not early on.

I think this is unnecessarily pessimistic.  Certainly, present the
"one-off" contributor case first.  This absolutely must be as smooth,
fast :-(, and effortless as possible, for the reasons already given.

First, set up your user.  This means checking that bzr naturally
presents the appropriate "Full Name <mbox at unix.rules.yo>" for logs,
and setting up your bzr config to use the persona you use for
community contributions.  Windows and Mac users may want to take
prophylactic action against EOL and case-insensitive file systems.
(I don't think this feature has made it into the mainline yet, but
people are surely gonna ask!)

Next, do an appropriate checkout for one-off patches, hack, commit,
submit.

Next, show the review process (eg, branch an existing workspace, apply
patch/bundle, commit to branch, test, merge to mainline).  This is
done *without* discussing the relevant optimizations to repository
setup (those will be done in a separate chapter, see below), just to
show the newbie user how that kind of thing is done.

And so on, to scenarios with more and more contributor commitment and
more complex/efficient VCS usage, such revising and resumbitting a
patch per reviewer comments, merging new code from upstream and
updating the patch, publishing a simple repo, etc.

OTOH, reviewer, maintainer, release engineer scenarios would be in one
or more separate "chapters".  Project workflow should also get a
separate chapter, and be presented after the reviewer et al.  (The
reviewer et al chapters could be introduced with a *very* short
discussion of workflow, maybe 2KB + 2 PNGs.  Cf not-so-tantalizing
footnotes, below. ;-)

I see no reason why this organization should be at all discouraging,
as long as the "get your feet wet" scenario is first up and
attractively simple and low effort.

 > We can have pointers to it, tantalizing footnotes that say things
 > like "If you're planning to be a regular contributor to project
 > foo, then you can set things up in a more efficient way -- see
 > <HERE> for details."

I don't think that's a good idea.  I (for one) don't find such
footnotes tantalizing, I find them foreboding.

 > It's certainly possible that prior VC knowledge got in my way:
 > caused me to expect things to work a certain way, where if I'd been
 > ignorant I wouldn't have had those misleading expectations.

Indeed.  This is especially true if you have experience with git or
darcs, both of which are quite different from hg and bzr, which I find
to be quite similar in general though the areas of focus are different.

 > > I don't think that follows at all.  A user can always start casual, and
 > > easily upgrade their set-up as they become more involved.  No one is
 > > forced to decide beforehand.
 > 
 > Great!  We'll need to document that upgrade step, then.

I think this is a bit optimistic.  From reading people's HOWTO
requests here, things like "do you structure your workspace with a
project focus or module focus?", "shared repo or not?", etc do seem to
run into obstacles requiring reorganizing some repos, with somewhat
careful planning.