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

[Karl Fogel]

"Stephen J. Turnbull" <stephen at xemacs.org> writes:
> 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.

This ordering seems quite reasonable to me.

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

Hmmm.  Okay.  They're not necessary, and if they might scare off some
people, let's leave them out.

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

Then let's just not talk about efficiency upgrades.  Those who care,
will find out.  We first need to make sure that for those who don't
care, everything Just Works, efficiently or otherwise.

-K