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

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.

> 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 '$.*').

> 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 '--'.

> Once we have these elements, the template format becomes arbitrarily
> extensible in a backward-compatible way.
>
> I propose the following:
>
>    * Author comments are lines that begin with a hash (#). Example:
>
> # The user will not see this line.
>
>    * The format indicator is a form of comment that must appear in the
> first line of the template, and contains the major and minor number of
> the Subversion release in which a particular template format is supported:
>
> #! format=1.9
>
> This implies that if 1.10 supports the same template format as 1.9, then
> "#!format=1.10" would be valid and would imply the 1.9 template format.
> This will make it easy for admins to note the oldest still supported
> version of SVN.
>
> Incidentally, we just established /^#! *[:keyword:]/ as the pattern for
> any future processing directives.
>
>    * User-visible comments are lines that begin and end with two dashes
>      (--). Example:
>
> -- The user will see this, but it won't appear in svn:log. --
>
> We've essentially already established this syntax with the "ignored" line,
> and I see it's also used on the branch.

Largely sounds good.

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.

The use of formatting directives on separate lines is, in principle, enough to support any future extensions. In practice, however, for convenience we may very well want to introduce substitution fields within a line, and a way to attach a user-visible comment to a specific field within a line, and such like. The 'format' mechanism gives us the upgrade path whereby we can do this. For example, a new format might introduce ${...} as a substitution syntax framework (and '\$' as a new escape producing a literal '$'). The 'plain text' parts would no longer be plain text, and so we must define how a client will process a format that is too new for that client.

An example template illustrating the use of different formats:

[[[
#! format=1.11
## Subversion >= 1.11 knows which log messages apply to which branches
## and displays them appropriately, so we no longer want this bit of the
## template.
#! format=1.10
## Subversion >= 1.10 knows how to substitute a branch name.
On the '${branch_name}' branch
#! format=1.9
## Subversion 1.9 supports static text and user-visible comments.
-- Please fill in the branch name here --
On the '' branch:
]]]

I would propose these versioning rules:

  * A template can contain multiple sections, each of a different format.

  * 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.

  * A client uses exactly one section, which is the section with the
    highest format number that the client supports. If there is no section
    with a format number that it supports, it SHOULD show a blank template.
    (It SHOULD NOT show the raw template, as it may not be suitable for
    display -- for example it might contain a huge block of encoded data
    representing an image.)

- Julian
Received on 2014-09-15 16:47:06 CEST