[MERGE] Add user doc for stacked branches

[James Westby]

On Fri, 2008-07-11 at 12:44 +1000, Ian Clatworthy wrote:
> The attached patch should only be merged after the stacked branches
> code lands. It also assumes that the --reference option to push
> will be renamed to --stacked-url as poolie suggested (IIRC) in a
> review.

Hi Ian,

Thanks for working on this, it will be good to have some documentation
available at the same time as the feature.

I have a couple of minor comments, but I think the patch is good
overall.

> +* Security is improved over shared repositories: developers with
> +  access to a shared repository can programmatically get to all
> +  revisions, while they cannot get to the local revisions in a
> stacked
> +  branch in a secure location.

I had to read this a couple of times before I grasped what aspect
you were talking about here, is there a way that it can be made
clearer? Assuming "get to" means "read", does "secure location"
convey the meaning correctly? If you don't want me to read
the revisions in a branch then you can't give me read access to
it.

I thought that there were two main security benefits of stacked
branches. Firstly that your branch could share revisions with mine,
without me granting you access to write to the repository that contains
my revisions, and so open up the possibility that you delete them all.
Secondly, the one that you focus on, which is that your branch
can share revisions with mine without me being able to access the
revisions. Is it your intent to only mention the second?

> +  bzr branch --stacked source-url my-dir
> +  cd my-dir
> +  (hack, hack, hack)
> +  bzr commit -m "fix bug"
> +  bzr push --stacked my-url

I think it should be made clear here that "my-url" is the push
location, not an argument to the --stacked option, probably be
explaining that this will create a branch at ``my-url`` which
is stacked on ``source-url``.

> +The important thing to remember about a stacked branch is that the
> +stacked-on branch needs to be available for many operations.

Rob says that opening the branch will currently require the stacked
on branch to be opened, so "available for all bzr operations." would
be better. He says we could perhaps also mention that in the future
this may be relaxed to only require the stacked on branch when data
is needed from it.

Thanks,

James