[rfc] bzr-colo into core

[Martin Pool]

{summary}

Let's make bzr-colo the default model for bzr 3.0 in September.


{the problem}

At the moment there are various different ways to use bzr: checkouts
from a separate repository directory; bzr-colo; checkouts with local
commits; standalone branches.  This gives users some flexibility but
it also makes some things confusing, and it's easy for people to end
up with a setup that's quirky, or that doesn't work well for them.

I see at the moment that a lot of support interactions need to start
by asking the user just how they have things configured, and that
sometimes just the variety of possible configurations does confuse
people.  (For example just as I write, there's someone on irc wanting
to know how to bring in new revisions from trunk and the answer is
that it depends on whether he has a checkout or a branch, and it's not
always obvious to users what they do have.)

People working on large trees really want to have just one on-disk
checkout at a time, so they don't use too much disk space and so they
don't waste time building a new tree just to start a new branch.  That
case is supported at the moment through either setting up a branch and
a tree-less repository, or through various plugins, but it's not
completely natural.

Whatever we do here, we should not put people through a painful or
compatibility-breaking upgrade process.


{a solution}

I think our user experience would be better if there was one clear
main path that led to a setup that could work well for all or almost
all users.

I think bzr-colo is pretty well suited to be that default and we
should aim to make that our main path in the next major release of
bzr, 2.4, in about September 2011.

If you haven't yet tried bzr-colo I really recommend installing it and
trying it out, both for your own sake and so we can get more input on
whether it's right to be the standard UI.

By "the main path" I mean this is the way that the documentation,
help, and command defaults guide people to working.  Since bzr-colo is
currently a plugin to do this we would have to either make sure the
plugin is installed for everyone using bzr, or to merge it into bzr
(perhaps updating some of the code on the way.)


{what is bzr colo}

Basically what bzr-colo does is give you multiple bzr branch
directories underneath .bzr/branches, in a directory that also
contains a repository and (usually) a working tree.  There is also a
.bzr/branch directory that basically indicates which of the colocated
branches is active.  You can switch between them just with 'bzr switch
BRANCH_NAME'.  You can also address any colocated branch from the same
bzrdir with eg 'bzr diff -r colo:other_branch'.

http://doc.bazaar.canonical.com/plugins/en/colo-plugin.html


{why?}

bzr-colo gives us several very nice things, that I think really belong in core:

 * easy setup of a workspace with a single tree and multple branches
 * a way to push and pull whole sets of branches
 * a way to clean out unreferenced content


{what else this gives us}

This addresses a few use cases that aren't well handled using only
built ins at the moment:

- cleaning up unreferenced revisions (bzr-colo-clean, also bzr-gc)
- pushing and pulling whole sets of branches, to publish all your work
(bzr colo-sync-to), to bring in your own state from somewhere else
(bzr colo-sync-from) and to update your mirror of other brancehs (bzr
colo-pull)
- getting a copy of a bunch of other branches (bzr colo-fetch)
- named branches on top of which we do policy layers like looms and pipelines

Many of these have point solutions in different plugins or through
manual configuration but I think they would be better in core.


{side paths to keep}

Some users have cases that are a bit different, and if we have
something that suits them well now we should try to keep that.

bound branches - For instance being able to have a single branch
that's synchronously updated by multiple people, such as a
team-maintained trunk, is a strength of Bazaar, it seems to be
appreciated by many people, and the implementation is pretty clean.
We can easily keep this by letting branches within a colo be bound to
a (probably remote) branch.

It seems like this could logically be supported within bzr-colo, but
it may not be trivial.

separate checkouts - Useful when you want to leave uncommitted work
around, and the tree is relatively small enough that you don't mind
having a few copies around.  (Easily created with bzr colo-checkout.)


{what would be removed}

On the other hand, there are some side paths that may have some value
but not enough to justify the confusion they might cause for

Generally we should prefer setups that can be represented both to the
user and in the code as composing reusable objects, rather than as
special cases.

local commits - I think we should deprecate 'commit --local'; it is
half-way between a real local branch and a simple checkout, and I
think many situations where people use them they would be better off
with one or the other.  We get some bugs and some user confusion from
the fact that it's neither one nor the other.

command synonyms - I made a mistake by leaving many hypothetical
command names actually in use, such as 'bzr get' for branch.  These
can only cause confusion, and they prevent us using those words for
other operations.  We ought to remove them.

distinctions between lightweight and heavyweight checkouts vs bound
branches; I think probably we want a checkout (just a tree plus a
branch) and then a bound branch.



{what would we have to do}

bzr-colo is mostly nmb's work; I haven't spoken to him about this idea
ahead of this mail but I hope he'll like the idea.

If you see problems with any of the above, or have better ideas, please do say.

Crucially we would need to update the main user documentation to give
a good explanation of how to do everything using bzr-colo type layout.
 Updating the tutorial-type documentation to show how to use it could
be a good next step if we agree in principle to do this.

If these are going to become the main ways to use bzr they should
perhaps get shorter names, losing the colo- prefixes.  In some cases
they would then clash with some builtins so we'd have to work out what
to do there.

We have to work out how, if at all, to deprecate existing commands and
ways of doing things.  Perhaps to start with it's enough to just have
clear documentation for the recommended path.

We'd need to think about how this would integrate with Launchpad,
which at the moment deals only with single branches.  It may be
reasonable to may each ~user/project container to being effectively a
branch set.

For pushing and pulling whole sets of branches we may want to add
single hpss verbs that check or gets all branch tips in a single
roundtrip.

I think it will work to stack looms and pipelines on top of this,
since they really just manage relations between branches implemented
at a lower layer.

Probably if we go ahead with this there will be some rough edges that
ought to be fixed both in bzr colo and bzr core to make them fit
nicely together.


{the bottom line}

I think this is the logical next step to make bzr's ui more powerful
and more friendly.  I'd like to start on this; I think we can get it
done in the next 6-month cycle and I think it will work well.


Martin