Mailing-List: contact dev-help@subversion.apache.org; run by ezmlm
Precedence: bulk
Received-SPF: pass (athena.apache.org: domain of brane@wandisco.com designates
 209.85.212.172 as permitted sender)
Message-ID: <5416DAD8.7070602@wandisco.com>
Date: Mon, 15 Sep 2014 14:26:00 +0200
From: =?UTF-8?B?QnJhbmtvIMSMaWJlag==?= <brane@wandisco.com>
Organization: WANdisco
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9;
 rv:24.0) Gecko/20100101 Thunderbird/24.6.0
MIME-Version: 1.0
To: dev@subversion.apache.org
Subject: Re: [VOTE] merge the log-message-templates branch to trunk
References: <20140910170607.GD9666@ted.stsp.name>
 <CAOGLoJN-9BsB4RMDT+ZNfxy3tn0Y0OTN_0ZTZuvqDARAZy-f5g@mail.gmail.com>
 <1410767917.10930.YahooMailNeo@web87701.mail.ir2.yahoo.com>
 <20140915083431.GN9666@ted.stsp.name>
 <1410773142.90170.YahooMailNeo@web87705.mail.ir2.yahoo.com>
In-Reply-To: <1410773142.90170.YahooMailNeo@web87705.mail.ir2.yahoo.com>
Content-Type: multipart/alternative;
 boundary="------------070207090303020205080304"

This is a multi-part message in MIME format.
--------------070207090303020205080304
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

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


--------------070207090303020205080304
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit

<html>
  <head>
    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <div class="moz-cite-prefix">On 15.09.2014 11:25, Julian Foad wrote:<br>
    </div>
    <blockquote
      cite="mid:1410773142.90170.YahooMailNeo@web87705.mail.ir2.yahoo.com"
      type="cite">
      <blockquote type="cite">
        <pre wrap="">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?</pre>
      </blockquote>
    </blockquote>
    <br>
    [...]<br>
    <br>
    <blockquote
      cite="mid:1410773142.90170.YahooMailNeo@web87705.mail.ir2.yahoo.com"
      type="cite">
      <pre wrap="">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}'.</pre>
    </blockquote>
    <br>
    <br>
    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.<br>
    <br>
    Here's what I think is missing from the template implementation. We
    should define three syntactic elements for the svn:log-template
    property value:<br>
    <ul>
      <li>Comment syntax! It's amazing how often we forget about that.<br>
        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 <i>before</i> 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.</li>
      <ul>
        <li>Implies an API for stripping comments from the property
          value<br>
        </li>
      </ul>
      <li>Template format indicator. This can essentially be just a
        comment-like processing directive</li>
      <li>Comment syntax! Yes, again. :) The second kind of comment,
        which is shown to the user but not included in the final log
        message.</li>
      <ul>
        <li>Again, implies an API for stripping those from the log
          message and extracting them from the parsed template by GUI
          clients.</li>
      </ul>
    </ul>
    <p>Once we have these elements, the template format becomes
      arbitrarily extensible in a backward-compatible way.<br>
    </p>
    <p><br>
      I propose the following:<br>
    </p>
    <ul>
      <li>Author comments are lines that begin with a hash (#). Example:<br>
        <br>
        <tt># The user will not see this line.</tt><br>
        <br>
      </li>
      <li>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:<br>
        <br>
        <tt>#! format=1.9</tt><br>
        <br>
        This implies that if 1.10 supports the same template format as
        1.9, then <tt>"#!format=1.10"</tt> 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.<br>
        <br>
        Incidentally, we just established <tt>/^#! *[:keyword:]/</tt>
        as the pattern for any future processing directives.<br>
        <br>
      </li>
      <li>User-visible comments are lines that begin and end with two
        dashes (--). Example:<br>
        <br>
        <tt>-- The user will see this, but it won't appear in svn:log.
          --</tt><br>
        <br>
        We've essentially already established this syntax with the
        "ignored" line, and I see it's also used on the branch.<br>
      </li>
    </ul>
    <p>-- Brane<br>
    </p>
  </body>
</html>

--------------070207090303020205080304--