[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

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

From: Stefan Sperling <stsp_at_elego.de>
Date: Mon, 15 Sep 2014 12:58:55 +0200

On Mon, Sep 15, 2014 at 10:25:42AM +0100, Julian Foad wrote:
> 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.)

Agreed.

> 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).

Or we could decide not to support a help message.

The help message would have to become part of the static template
itself, such as:

[[[
PR: Put a PR number here if applicable.
]]]

And people would be required to delete all lines that shouldn't be
in the final log message.

> 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.

This leads to duplicing information once in svn:log (where the user
will want to view the information) and other revprops (which might
be useful for automated tools but too cumbersome for users to view
with the current UI).

I'd say let's keep this feature scoped to the content of log messages,
not the content of arbitrary revprops.

> 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 thought about this, too. Then I used our own log message style as an
example and tried to come up with a template syntax to describe it in
a simple way.

I thought that perhaps we'd want something to repeat a template pattern for
each changed path, such that we can expand e.g. a template such as:

[[[
%{ * %p: }
]]]

to a log message such as the following when someone commits two files:

[[[
* subversion/libsvn_client/update.c:
* subversion/libsvn_wc/upgrade.c:
]]]

I discarded these ideas because they add a lot of comlexitity and I didn't
want to design a general purpose and potentially recursive templating mechanism.

> I recommend we anticipate this now by defining a minimal syntax for substitutions.

Whatever we come up with now might not fit a future substitution feature.
I'd say either we define the feature completely, or we leave it out.

We don't have to define substition rules now. The path for that is always
open during later iterations of the feature.

> 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.

I think it's fine to keep the current svn:log-template and perhaps add
a different svn:magic-log-template or whatever property later.

> 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?

Our log message syntax is quite complex compared to most other projects.
For ourselves, we'd ideally build something that creates the skeleton of
a log message including function names, such as:

[[[
* subversion/libsvn_client/update.c:
  (svn_client__dirent_fetcher):
* subversion/libsvn_wc/upgrade.c:
  (read_propfile):
  (svn_wc__upgrade_add_external_info):
]]]

But I suspect that if we go down this path of perfection, this feature is going
to end up eating a lot of our time that would be more wisely spent elsewhere.

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

I don't know. I was hoping to get something finished that satisfies the
FreeBSD use case, and nothing else. They obviously have a need for this,
else they wouldn't have written a custom patch. AFAIK nobody else has
loudly complained about the lack of this feature or made concrete
proposals for what it should look like.
Received on 2014-09-15 12:59:42 CEST

This is an archived mail posted to the Subversion Dev mailing list.