[rfc] format numbering (was Re: bazaar 2.0beta format for launchpad release)

[Martin Pool]

2009/6/3 Andrew Cowie <andrew at operationaldynamics.com>:

> Anyway, if bzr mainstream formats were increasing in a manner like this
> not in lockstep with the software release version number, we'd be at
> some version that would have nothing to do with "2.0" and so "wouldn't
> require a further upgrade".
>
> The cost, of course, is people asking "what version of bzr do I need to
> work with repository format 29?" but surely `bzr --version` could tell
> you what it's up to, and we're getting that question from people now
> anyway.

That's an interesting point.  This is basically what we do with
internal formats anyhow: BranchFormat7 etc, so perhaps we should also
do that for the user-visible format.  On the other hand the Java
approach apparently causes some confusion.

To take a step back, each format has at least these attributes:

 * the actual format grammar
 * a format marker string stored on disk
 * some kind of handle or name by which we describe it to the user
 * the earliest version of bzr that supports it
 * a set of formats for which this is the best recommended format
 * a set of formats for which this is the default format (this has
historically diverged too much from the previous point)
 * whether this is a stable supported format or an experimental format
(or somewhere else on that spectrum)
 * a set of other formats with which it can or can't interchange data.
 (rich-root was a bad example of this, but there may still be things
in future where we only support forward upgrades.)
 * features that this format supports (like stacking)

It may be useful to think about which of these should or shouldn't be
tied together.

When the actual format changes, we need a new format marker.  But
sometimes the opposite is true, and we need to rename a format without
actually changing what's stored, for example in promoting a format
from being experimental to supported, and that seems possibly
wasteful.

When some code is under development or when it's merged as an
experimental format, it's hard to predict in what release it will be
finally released as the new default.  For example RepositoryFormatCHK2
says it needs bzr.dev from 1.15; that's a bit misleading because it
means it needs something later than 1.15 (I think.)  We can control it
by bumping to a new major version at that point, like saying that when
brisbane-core is finished it'll be called 2.0 and it'll be in 2.0, but
that may mean, as here, that the format will actually be supported
before we get to 2.0, which is a bit strange.

On the other hand if we're going to do format bumps only on major
versions, which makes sense to me, then numbering them on an entirely
unrelated scale seems perverse.

If you change a format from being experimental to being stable with no
further changes, which seems like something we generally should be
doing, it'd be good not to have to change its name either on disk or
(perhaps) in the ui.

We probably do want the ui to do something to discourage users from
accidentally using unstable formats.  In combination with the previous
point this means that bzr x.y might warn you off using a particular
format, but a later release that knows that format's now stable and
supported may create exactly the same thing with the same format
marker.

The metadir, branch, repository and working tree have independent
version markers; you can upgrade them separately.  So when you say
'1.9' that means a set of formats for those different components.
This may be a separate bug; certainly one we want to fix in post 2.0
ui.

At the moment it's not easy to map from the on-disk format string to
the ui name for it.

For mainstream bzr formats there might be a linear progression, but
people may want to try other experiments.  We certainly could use
integers but it may not be a monotonic progression of features.

When bzr sees a directory it recognizes as a bzr directory but whose
format it doesn't support, it shows the raw format string to the user,
so it's nice for that to make at least some of these points clear.

Using external names based on descriptions of the code that implements
them, as we did with eg 'knit' is poor, because users can't perceive
any ordering between the names, and because any particular format is
typically a combination of multiple such aspects.  On the other hand
using numeric names for classes is not so good.

We could do this:

 * Stop putting into the format string whether it's a development
format or beta format etc not; just make that metadata about the
format that can be changed later on if it becomes stable
 * Assign the format string by the series in which it's going to be
stable, so for things introduced in 1.15 targetted to be the 2.0
default, call them say '2.0.1' or '2-0' or '2a' -- something related,
but that doesn't look just like a release number
 * I'm still split on whether to include in the format string the
release that first supported it - it is helpful but getting it right
causes some disruption in merging and testing the format - on the
whole I think it's worthwhile
 * '--format 2a' as the ui to create this

If people agree, we should bump the brisbane-core repository formats.

-- 
Martin <http://launchpad.net/~mbp/>