[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [VOTE] merge the log-message-templates branch to trunk

From: Branko Čibej <brane_at_wandisco.com>
Date: Mon, 15 Sep 2014 18:24:47 +0200

On 15.09.2014 16:43, Julian Foad wrote:
> Hi Brane.
>
> Isn't this fun, brainstorming a new feature (re)design?
>
> Your proposal contains good points about adding a format number and a comment syntax as well as an extensible command syntax.
>
> Branko Čibej wrote:
>> On 15.09.2014 11:25, Julian Foad wrote:
>>> [...] We will want to upgrade the
>>> functionality. One of the obvious upgrades is we will want to insert
>>> run-time substitutions in the text. I recommend we anticipate this now
>>> by defining a minimal syntax for substitutions. For example, we may
>>> want to use forms like '$foo' and '${foo bar}'.
> You snipped the bit after the examples, where I stated what my proposal actually was, thus giving the impression that you thought my proposal was to define minimal syntax(es) looking like '$foo' and '${foo bar}' specifically.

Yes, on purpose; see below.

>> Allow me to very strongly disagree with this idea. :) For a simple
>> reason: the kind of substitutions we may potentially want to support
>> are merely a matter of speculation right now.
> Allow me to observe that your proposal for reserving '^#!.*$' as the syntax for new directives is one specific implementation of my actual suggestion.
>
> I didn't mention it at the time, but a minimal syntax where the extent can be recognized (such as '${.*}' or '^#!.*$') has advantages over one where the extent cannot be recognized (such as merely '$.*').

In a way it is, but in a different way than you seem to assume.

>> Here's what I think is missing from the template implementation. We
>> should define three syntactic elements for the svn:log-template
>> property value:
>>
>> * Comment syntax! ... not shown to the user
>> * Template format indicator.
>> * Comment syntax! Yes, again. :) ... shown to the user
> And:
>
> * An escape syntax to enable specifying log template text which (when shown to the user) must contain a character sequence reserved for template mark-up, such as a line starting with '#' or with '--'.

Nope. We really do not need this for the initial implementation. I'll
skip most of the rest of your mail, not because I don't think it has
merit (quite the opposite), but because I think it's largely irrelevant
for the initial implementation.

We do not need to invent a replacement syntax, since no-one is planning
to support replacement text in the template. Furthermore, some future
template processor could do a lot more than just replace bits of text,
so it's premature to try to invent a "sufficient" syntax now (it's also
painful to invent a template syntax at all, since there are some
moderately standard ones out there).

We do not need an escape syntax because it's not /likely/ that any log
message would need either "#" or "--" in the first column. Once users
get used to treating these as comments, it will become even less likely.

If at some point it becomes evident, through experience, that we really
do need an escape mechanism, then the solution is "#!escape=\" or
"#!comment=//" or even just "#!format=1.13", which could invent its own
inline comment and escaping and whatnot syntax. But we do not /need/ any
of that right now, so it's a waste of time to try to implement it.

[...]

> For the escaping I'd suggest:
>
> * Three backslash escapes are recognized everywhere in the literal text:
> '\\' -> '\'
> '\-' -> '-'
> '\#' -> '#'
> Backslash followed by any other character is undefined, and SHOULD be
> displayed in some way that indicates it is undefined.

Most escaping mechanisms make the behaviour of undefined escape
sequences well-defined (q.v., PCRE or C, for example), because error
reporting for that is really hard in many contexts.

> * A client SHOULD support the current format "1.x" and also at least the
> format of the previous release "1.(x - 1)", regardless whether those
> formats are identical or different. The 'svn' client provided by the
> Subversion project SHOULD support the current format "1.x" and all
> previous formats.

I'd rephrase that as: A client MUST use the provided APIs in order to
handle all template formats that are supported by the underlying native
libraries. It is IMO a mistake to delegate template parsing and
semantics to the client, when libsvn_client (and libsvn_subr) should
really be encapsulating the complexity.

A.k.a we MUST provide a minimal set of APIs for templated log message
handling.

-- Brane
Received on 2014-09-15 18:25:31 CEST

This is an archived mail posted to the Subversion Dev mailing list.