Rule-based preferences - format marker RFC, etc.

[Ian Clatworthy]

Martin Pool wrote:
> On 6/24/08, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
>> John Arbash Meinel wrote:
>>  > John Arbash Meinel has voted tweak.

> If we are going to have a marker that is probably a reasonable syntax.
>  It would possibly also be ok to use an ini-style variable setting,
> but using the line with a hash has the advantage it can be prepended
> to files other than an ini file, and detected in reading just the
> first bit.

Right. Then again, taking your point later on to its logical conclusion,
if we were to change from ini-format to xml format, then using a new
filename (like .bzrrules.xml) would make far more sense.

> Whether it's required or optional, we need to consider what will
> happen if the format marker is unrecognized, incorrect or missing (in
> the case that it's required.)  Broadly, it seems like we would have
> the choice to give an error, a warning or no indication; and in the
> latter two cases to either interpret the file according to a best
> guess as to its format, or not use it at all.  Saying "required" is
> not really an answer; we need to say "required otherwise the file is
> silently ignored" or "required otherwise commits fail" to really
> assess it.

Silently ignoring it is out IMO. I had been thinking about giving
a warning - "ignoring rules file" - and proceeding. Semantically,
these are meant to be preferences so failing altogether felt over
the top. I could easily convince myself though that our primary
responsibility is to protect the integrity of the code we're
managing and aborting with an error is a safer path.

> The relevant cases seem to be:
> 
>  [0] version marker is just what we expect
>  [1] user mistyped or otherwise mangled the marker and it is not valid at all
>  [2] version marker is the one from an older version of bazaar than is
> now being used, and we can still interpret it under the old rules
>  [3] ditto, but we don't support it any more
>  [4] the marker is for a newer version of bazaar than is currently
> running, so we don't properly know how to interpret the file

[1] and [4] could be treated as the same case. I don't think
[3] is an option: once we support a format in a user-space file,
I believe we're implicitly committing to supporting it "forever".
So, if we go the format marker road, we're arguably down to:

[0] all ok
[1] unknown
[2] use the old rules to parse this file

If and only if warning about an unknown format is good enough, then
making [4] separate to [1] make sense - we could handle the bits we
understood and narrow down the warning to the rest. (That implicitly
assumes upwards compatibility in formats.) Given ordering of rules
though, partially interpreting the file could have scary consequences?

> Case [4] could easily happen if this is added without an overall
> tree/repository format bump, and somebody checks out the tree with an
> older client.  Of course it's not going to happen for the one version
> transition we are sure will happen, which is the one where this is
> first added.

Agreed. Though I'd only expect to produce the error/warning the first
time the preferences are looked up, and that will never happen in a
released version of Bazaar (like 1.5) until after this code lands.

> If we want new rule syntax then
> perhaps we just need to make sure the syntax itself has room to grow.
> For example if the section headers were
> 
> [glob *.py]
> 
> then we can add more in future, and potentially also check whether all
> of them are understood by the current version.

Right. You've convinced me that completely changing the format without
changing the filename itself just isn't going to happen. So the issue
degenerates to how might we evolve the way we interpret the content.
I believe any future "format" will be upwardly compatible, syntax wise
at least, with the current one for pragmatic reasons.

> If people do want them then I'd
> come back to having a way for the user to say "this tree should be
> used with bzr version >= X, and with plugins Y and Z."  I suppose that
> could be done either in the tree itself or in branch.conf.

Or we could drop the format marker idea and make these requirements a
section of the rules file. For example:

[requires]
bzr=1.6
bzr-eol=0.1
company-policy-plugin=2.1

I kind of like this because it solves several problems at once.
If someone starts using either a syntax (or preferences for that matter)
only supported in later versions of Bazaar (or a plugin), they can make
that explicit. It also makes it easy for us to tell the user what they
need to work on this branch.

>>  I guess it would be nice if the pattern chosen was adopted (in the future)
>>  for .bzrignore as well?
> 
> Honestly I don't really see the problem.  We had one transition a long
> time ago; we should have thought more about what the defaults were
> going to be before adding it but it's not something we're often
> changing.  We have ways to add new syntax if it's needed.

In the case of .bzrignore, the semantics are arguably very simple and
stable so the issue is solely about syntax IMO. I agree it's no big deal.
My suggestion about adding a [requires] section to .bzrrules would solve
it anyhow, wouldn't it?

Ian C.