Mini tutorial doesn't explain repository directories

[Maciej Katafiasz]

http://doc.bazaar.canonical.com/latest/en/mini-tutorial/index.html#creating-your-own-copy-of-another-branch
This starts off by making a repo, without explaining what it is and what it's for. It really shouldn't be doing that when presenting the simplest possible way of branching an existing repo.

[Martin Pool (mbp)]

Hi, thanks for the suggestion.

We don't want to encourage people to just make standalone branches because that scales poorly when they make large branches. So, the mini-tutorial should still tell them to use init-repo. However, possibly it can be improved by:

 * being merged with a larger tutorial
 * explaining what the repository directory is for

[Maciej Katafiasz (mathrick)]

Fair enough, though I'd still leave in the mention of just 'bzr init' to avoid creating the impression of excessive complexity on bzr's side. The mini-tutorial is a reasonable "just get me going as fast as possible" entry point for people new to bzr, many of whom will have enough technical chops to decide whether they want to bother. That's in fact how this bug came around to be reported, as I wanted to collaborate on a small personal project with a friend who hasn't used bzr before.

Now actually to improve the wording, where is the source for the tutorial I could poke? I'm not up for the merging part (I'm not even sure it's beneficial to remove the mini-tutorial), but adding a note box explaining the why of init-repo is trivial enough.

[Martin Pool (mbp)]

It's in the bzr source tree - Google 'bzr giving back'.