subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Branko ─îibej <br...@wandisco.com>
Subject Re: [VOTE] merge the log-message-templates branch to trunk
Date Mon, 15 Sep 2014 12:26:00 GMT
On 15.09.2014 11:25, Julian Foad wrote:
>> And perhaps we could introduce a template syntax to specify
>> key-value pairs (e.g. "%KEYWORD:%") which are removed automatically
>> if the value is left empty?

[...]

> UPGRADE PATHS
>
> Once we release this, the 'svn:log-template' property will exist in people's repositories
for all time, and for all clients (although only clients that query it will see it).
>
> 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}'.


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.

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! It's amazing how often we forget about that.
    By "comment" I don't mean something that's shown in the log message
    editor, but something that causes parts of the property value to be
    ignored /before/ it's sent to an editor. If we predict that
    templates may someday contain non-trivial markup, the author of the
    template has to be able to explain, with comments, what the markup does.
      o Implies an API for stripping comments from the property value
  * Template format indicator. This can essentially be just a
    comment-like processing directive
  * Comment syntax! Yes, again. :) The second kind of comment, which is
    shown to the user but not included in the final log message.
      o Again, implies an API for stripping those from the log message
        and extracting them from the parsed template by GUI clients.

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.

-- Brane


Mime
View raw message