subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Julian Foad <julianf...@btopenworld.com>
Subject Re: [VOTE] merge the log-message-templates branch to trunk
Date Mon, 15 Sep 2014 14:43:34 GMT
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

Mime
View raw message