Subtree watershed warning

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Warning
=======
The dirstate-with-subtree format is a watershed.  If you upgrade to it,
you cannot go back.  So do not upgrade to it unless all the users of
your branches can easily upgrade to bzr 0.15.

Technical explanation
=====================
The dirstate-with-subtree format uses a slightly different model from
the "dirstate" or "knit" formats.

The main things are
1. It allows inventories to contain references to subtrees.
2. It only considers the root entry to have changed when it really has
changed.[1]  This is in contrast to knit, which considers the root entry
to have changed for every commit.

If 1 were the only change, there would still be common cases where we
could import losslessly from a "dirstate-with-subtree" repository into a
"knit" repository.

But because of 2, every commit that is made to a "dirstate-with-subtree"
repository cannot be losslessly imported into a "knit" repository.

In Bazaar, we cannot use the same identifier for two versioned objects
unless they are equal.  So we cannot do lossy revision imports without
changing the revision-id.  It seems doubtful that anyone would want to
do that.

[1] The root entry, being a directory, is only considered "changed" if
it is moved or renamed.  Yes, it is now possible to move a root entry.
"bzr join" effectively does this to the subtree's root entry.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFF7tUf0F+nu1YWqI0RAp1QAJ9KdGwpIhPL0bWWpZsMvb3acHZcBwCeJbeq
tU0iGbB7IRZEnFoAi/t+LIw=
=1klX
-----END PGP SIGNATURE-----