Re: [vote] pin-externals branch to trunk

Stefan Sperling wrote:
> On Tue, Feb 03, 2015 at 12:25:01PM +0000, Julian Foad wrote:
>>  This proposed log message seems to contain the documentation of the
>> feature. Can we put the documentation somewhere more widely accessible?
>>
>>  - in the book?
>>  - in the issue tracker [3]?
>>
>>  or at least document it here in email to begin with and then it can be
>> copied into such a place.
>>
>>
[...]
>>  On the branch this help text now says:
>>
>>    --pin-externals          : pin externals with no explicit revision to their
>>                               current revision (recommended when tagging)
>>
>>  Would this be slightly better?
>>
>>                               pin each external with no explicit revision to the
>>                               copied revision (recommended when tagging)
>
> I think "copied revision" is misleading. The revision number of the copied tree
> has no relation to the revision numbers which externals will be pinned to.
> Externals generally point at other repositories and therefore use a distinct
> revision number space.
>
> We now pin externals to their HEAD revision if the copy source is a URL.

Oh yes, makes sense. (My thinko. I was mistakenly thinking that the default revision for an external was whatever the revision of the directory carrying the svn:external property, but it's not; and that could only make sense within the same repository.)

> If the copy source is a WC, we pin externals to the revision they were
> found to be checked out with in the WC (and it's an error if an external
> is not checked out in the WC and the --pin-external option is used!).

(Not an error if an already-pinned external is not checked out, I hope.)

A checkout of a tree is, in general, mixed revision. I can see how using the WC revision feels right if it's a single-revision checkout: a future checkout will recreate exactly what was in the WC. But if it's mixed-rev, what do you do then, and why? I guess you take the root node's base revision and ignore the rest. A future checkout won't then recreate what was in the WC.

If the behavioural intent is to make a copy that looks like the WC, then in cases where that's not easily achievable, I think silently picking one revision is not a very robust behaviour. I think it would be preferable to error out or something.

Also if the external checked out in the WC is locally modified, then pointing to its base rev does not have the effect of preserving a snapshot of what was in the WC. Perhaps best to error out (or something) in this case too. And probably if it contains switched, sparse, etc. content too.

>>  Perhaps now adjust svncopy.pl's help text to mention that its '--pin-externals'
> option is similar to 'svn copy --pin-externals'?
>
> Good suggestion.
>
>>  To be clear, [...] 'svncopy --update-externals' [...] is not
>>  directly replaced by this new feature.
>
> Hmm. Perhaps we should just remove the entire script for 1.9?

I suggest leaving it there so that people already using it have a chance to change over gradually and to see any additional message that you insert in it.

>>> Externals are "pinned" by adding a peg revision to the external's
>>> source URL.
>>> For example, the external definition:
>>>   ^/foo/bar ext_bar
>>> might become:
>>>   ^/foo/bar_at_400 ext_bar
>>>
>>> An external that is already pinned is left as-is.
>>
>>  Could you expand this to mention both peg rev and operative rev, and both
>> the old and new formats? For deciding whether the external
>>  definition needs to be adjusted, after reading the book [1,2] I
>>  understand that the question "is it pinned?" translates to "is a peg
>>  revision OR an operative revision specified?".
>
> [...] We currently "pin" by adding a peg revision: ^/foo/bar_at_400 ext_bar

Ahh, so the question "is it pinned?" translates only to "is a peg revision specified?". I understand why: because if there's no peg then the URL (with implicit peg rev 'head') is not a stable reference.

(Note: In the old syntax, a revision specified as "-rX" acts as both a peg revision and an operative revision.)

> Pinning won't work with exernals which have been deleted in HEAD at
> the time the copy is made or the external is checked out into a copy
> source WC. In this situation a non-pinned external is already broken
> and we decided not to make any attempt of mending it because we'd have
> to make a guess as to which path at which revision the user wants.

Yes of course -- this should work analogously to 'update' and every other command that looks at externals. If they error out, or give a warning, or silently skip when an external target cannot be accessed, then this should behave in a similar way.

> Adding a peg revision to pinned externals has the advantage that tags
> with pinned externals will check out correctly even if an external
> they refer to is deleted from HEAD in the future.

Yes -- totally necessary if the intent is to produce a stable tag.

> Any -rN present in the externals definition is left as-is, since by
> definition -rN should be older than HEAD or a checked out copy of
> the external.

I get it now, and agree.

> Also, the kind of revision specification is left as-is,
> which is important in case a date is used in the definition:
> $ svn ps svn:externals -- "-r{2015-02-04} ^/branch/epsilon ext" .
[is converted to]
>     -r{2015-02-03T23:00:00.000000Z} ^/branch/epsilon_at_3 ext

I get the part about adding a peg rev and keeping the time stamp operative rev.

(Looks like timestamp revs have an issue with ambiguous time zone. That's a separate problem, but I wonder if converting it to a Zulu time at this point is the right thing to do.)

>>  When we change the definition to make it pinned, we add a peg
>>  revision. The example shows the new format (URL first).
>>  If the definition is in the old (PATH URL) format, do we change it to
>>  "PATH -rX URL" to keep using the old syntax with a peg rev, or convert to new syntax
>>  "URL_at_X PATH"? I think keeping the old format would be better, in that
>>  old (pre-1.5) clients may possibly still be using the repository and they would
>>  break if we changed to the new syntax.
>
> Good point. But I don't think it's possible to retain compat with the old
> syntax for the purposes of --pin-externals because the old syntax did not
> support peg revisions (which is why the new syntax was invented).

No: according to The Book, the old "-r" is a peg-and-operative rev, so 'PATH -rX URL' is exactly equivalent to 'URL_at_X PATH'.

> And unfortunately the parsed external representation doesn't convey which
> syntax was used in the property. I think this limitation is acceptable
> since the new format has been supported since 1.5 and even Debian is now
> shipping a more recent Subversion client than that :)

As is being discussed on IRC, if we need to do this, then we could convey that extra information through private APIs.

- Julian
Received on 2015-02-03 16:17:56 CET