[MERGE] Add user doc for stacked branches

[Colin D Bennett]

On Fri, 11 Jul 2008 12:44:18 +1000
Ian Clatworthy <ian.clatworthy at canonical.com> 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.
> 
> I don't yet explain stacked branch policies. I'm not sure exactly
> what to say about them in a user guide. Maybe the admin guide would
> be a better place to explain that (though it's just a TOC so far)?
> 
> The other thing that I'm yet to explain is the need for the
> development1 repository format. I'm wondering if --stacked should
> imply that? I'm also wondering whether requesting a stacked branch
> in a shared repo should just implicitly create a non-shared repo
> in that format for the newly created branch?

I think it should just tell the user that repo format X is required, in
the same way that if you try to branch a rich-root-pack branch into a
pack-0.97 repo (or use bzr-svn to create a branch in the repo).  If
there was a non-shared repo created implicitly within the shared repo,
it might confuse users.

Good to have the documentation.  In particular (and this may be old
news for some) I thought the comparison of stacked branches and shared
repositories presents an interesting way to think about stacked
branches.  My first tendency is to think of the "fast/cheap local branch
of Emacs/gcc/another-huge-project" use case, but pointing out some of
the other useful applications for stacked branches is great.  I look
forward to discovering how I can put stacked branches to use for
myself.  

One quick fix:

> +
> +Pushing a stacked branch
> +------------------------
> +
> +Most changes on most projects build on an existing branch such as the
> +*development trunk* or *current stable* branch. Creating a new
> +branch stacked on one of these is easy to do using the ``push``
> +command like this::
> +
> +  bzr push --stacked-url reference-url new-url
> +
> +This creates a new branch at ``my-url`` that is stacked on
> ``reference-url`` +and only contains the revisions in the current
> branch that are not already +in the branch at ``reference-url``.

s/my-url/new-url
"This creates a new branch at ``new-url``...

Regards,
Colin

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20080711/dc1e6eb2/attachment.pgp