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

Stefan Sperling wrote:
> On Mon, Sep 15, 2014 at 08:58:37AM +0100, Julian Foad wrote:
>> Justin Erenkrantz wrote:
>>> If the functionality follows what is described above, my only request
>>> is that we insert the template/property value *after* the ignore line
>>> - I don't think that these templates should be the default - but, they
>>> should augment/replace what is presented below the ignore line.
>>
>> I just took a look at the FreeBSD patch [1] that Stefan mentioned. It
>> actually inserts text both before and after the 'ignore' line, [...]
>>
>> A log message template with a 'will be ignored' line in it would
>> produce almost exactly this result with Stefan's current scheme. That would
>> work for a single template. Multiple before-and-after templates concatenated
>> wouldn't retain the overall before-and-after effect, unless [...].
>>
>> Also I wonder [...] if we should give the user a configuration option to
>> turn it off. [...]
>
> I think putting the template below the ignore line isn't very
> intuitive. What's the point of having a template if you're
> not always going to make use of it? [...]
>
> So perhaps a static template text isn't going to get us very far.
> An it seems we'll need some extra flexibility anyway to fully
> emulate the FreeBSD patch.
>
> Should we perhaps allow the template to indicate where the
> ignore line and changed-paths list should go?

TEMPLATES, HINTS and REVPROPS

The FreeBSD patch provides two things to the user. It provides a template to be filled in, and it also provides a help message describing how to do so. I think we need to recognize that these are different. (And we should not merely separate them with a command-line-client-specific 'ignore...' message.) So, maybe'svn:log-template' for the template part and 'svn:log-hint' for the help message part (which 'svn' would show below the 'ignore' line and GUIs would show elsewhere).

The top part of the FreeBSD log message, while being presented as a template, is effectively a group of property fields. Ideally for this sort of usage we would also provide an easier way of setting a group of revision properties, and not only support putting plain text in svn:log.

Instead of a 'get_log_message(list_of_commit_items)' we should have 'get_rev_props_for_commit(list_of_commit_items)', and instead of a template we should have:

  - a list of required and optional rev-props (usually including svn:log);
  - a template for each;
  - a help message for each.

> 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?
>
> So in the above use case the svn:log-template property would
> look something like:
>
> [[[
>
> %PR:%
> %Submitted by:%
> [...]
> %Sponsored by:%
> %ignore-line%
>> Description of fields to fill in above:                     76 columns --|
>> PR:            If a GNATS PR is affected by the change.
>> Submitted by:  If someone else sent in the change.
>> [...]
>> Sponsored by:  If the change was sponsored by an organization.
>> Empty fields above will be automatically removed.
>
> %changed-paths%
> ]]]
>
> And the resulting template presented to the user would be:
>
> [[[
>
> PR:
> Submitted by:
> [...]
> Sponsored by:
> --This line, and those below, will be ignored--
>> Description of fields to fill in above:                     76 columns --|
>> PR:            If a GNATS PR is affected by the change.
>> Submitted by:  If someone else sent in the change.
>> [...]
>> Sponsored by:  If the change was sponsored by an organization.
>> Empty fields above will be automatically removed.
>
> [... the automatic listing of changes goes here ...]
> ]]]
>
> Am I going overboard with this? :)

Not entirely.

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}'. To anticipate this, we could declare now that '$' is a special character and must be doubled ('$$') if it is to appear literally, and that any '$' not followed by '$' has behaviour that may differ between different (present and future) clients.

Another possible upgrade path is to introduce in the future a new property name ('svn:log-template2'? 'svn:log-template-with-substitution'?) for the new functionality, and keep supporting the old one for back-compat. If we anticipate taking this path in the future, then I would suggest the current version be called 'svn:static-log-template'. This upgrade path will always be open to us but is not always the best option.

EXAMPLES

Before we release this, I would like to see a couple more real-world examples of this feature in action, to see how well it meets real needs. Can we set an svn:log-template property (or
several) on our own Subversion development tree?

For example, we might set svn:log-template on '^/subversion/branches' to:
[[[
On the '' branch:

]]]

If not, if we don't want to do this, then: why not? Is the feature not suitable for our usage, or why do we not want to use it?

Are there other examples "out there" like FreeBSD but different?

- Julian
Received on 2014-09-15 11:26:14 CEST