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
Received on 2014-09-15 14:32:50 CEST