Short, task-based bzr doclets for real-world use cases.
p.f.moore at gmail.com
Fri Jan 16 09:56:12 GMT 2009
2009/1/16 Karl Fogel <karl.fogel at canonical.com>:
> [This mail is long, because it's trying to get experts -- you -- to
> recall a long-vanished time when you knew nothing about bzr :-) .]
I'm not an expert, just a lurker who worked a bit with bzr but then
found Mercurial more to his taste. But some of my reasons *why* I did
so mirror your comments, so I thought I'd chip in. I hope that's OK -
I don't mean to troll.
> This turns out not to have been the best way to organize things :-).
That in itself is an issue. In my view, the "natural" way for a new
user to work (ie., the one he stumbles on without needing help from
experts) should be correct (at least acceptable, if not optimal).
> The fundamental problem here is a combination of two facts:
> 1. Everything in bzr is done via branches.
> 2. Every potential branch comes with a bewildering set of choices.
3. Non-obvious approaches are correct; the obvious ones are sometimes
severely suboptimal. (The hugely over-used example of needing a shared
repo for performance, rather than a standalone branch, which is the
"obvious" approach, is the canonical example here; your example above
> Either of those alone would be okay; the two of them together create
> serious complexity. If bzr is going to be so flexible, we probably need
> to offer firmer guidance about how to use it for particular scenarios.
> What I have in mind are short, task-based documents saying "Here's
> exactly how you'd use bzr to do X", where X might be:
> - Start a new project in bzr (with intent to collaborate)
> - Maintain local changes against an upstream source over time
> - Publicly work on a bugfix for a project already in bzr
> - Publicly work on a bugfix for a project already in bzr (in Launchpad)
Publicly work on a bugfix for a project which doesn't use bzr (where
you are ultimately sending in patches)
> - Publish my changes to project Foo, independently of Foo's maintainers
> - Cooperatively maintain a web site in bzr, with automatic updates
> - Accept changes from others, for review and incorporation into a
> mainline that you are responsible for
> - etc, etc (suggestions welcome)
> I don't think we have much in the way of task-based guides right now.
> So how do we get more task-based documentation?
Maybe also the question should be asked - *why* are task-based guides
needed? Flexibility, in and of itself, isn't the reason - just because
there's a lot of options, doesn't mean the correct one in a given
situation shouldn't be easily discoverable. But maybe it's too late to
address that one.
> Thoughts? Rotten tomatos? Am I onto a real problem here?
It's definitely a real problem. And your suggestion is an extremely good one.
More information about the bazaar