[svnbook] r4420 committed - Finish issue 178 ("document ephemeral txnprops (new in 1.8) and how...

[Daniel Shahaf]

svnbook at googlecode.com wrote on Sat, Feb 09, 2013 at 06:35:00 +0000:
> Revision: 4420
> Author:   cmpilato at gmail.com
> Date:     Fri Feb  8 22:33:40 2013
> Log:      Finish issue 178 ("document ephemeral txnprops (new in 1.8) and 
> how
> hook scripts might use them.")
>
> * en/book/ch05-repository-admin.xml
>   (svn.reposadmin.hooks): Was svn.reposadmin.create.hooks.  Completely
>     rework this section to give some more useful examples of
>     implementing hook scripts.  Include hereing an example of checking
>     ephemeral transaction properties, and move the (short) list of
>     such props here from Chapter 3.


> +        <example id="svn.reposadmin.hooks.configuration.ex-1">
> +          <title>hooks-env (custom hook script environment
> +            configuration)</title>
> +
> +          <programlisting>
> +# All scripts should use a UTF-8 locale and have our hook script
> +# utilities directory on the search path.
> +
> +[default]
> +LANG = en_US.UTF-8
> +PATH = /usr/local/svn/tools:/usr/bin
> +
> +
> +# The post-commit and post-revprop-change scripts want to run
> +# programs from our custom synctools replication software suite, too.
> +
> +[post-commit]
> +PATH = /usr/local/synctools-1.1/bin:/usr/local/svn/tools:/usr/bin
> +

Isn't this the perfect place to use %()s substitutions?
(subversion/tests/libsvn_subr/config-test.cfg)

PATH = /usr/local/synctools-1.1/bin:%(PATH)s

(untested)

> +[post-revprop-change]
> +PATH = /usr/local/synctools-1.1/bin:/usr/local/svn/tools:/usr/bin
> +</programlisting>
> +        </example>


> +      <sect3 id="svn.reposadmin.hooks.uses">
> +        <title>Common uses for hook scripts</title>
> +
> +        <para>Repository hook scripts can offer a wide range of
> +          utility, but most tend to fall into a couple of categories:
> +          notification and change validation.</para>
> +

Another task that comes to mind is backup scripts (incremental dump in
post-commit, for example).  Not sure if it merits being listed in this
short paragraph.

> +        <para>
> +          <indexterm>
> +            <primary>properties</primary>
> +            <secondary>ephemeral transaction properties</secondary>
> +          </indexterm>Beginning in Subversion 1.8, clients committing
> +          against a Subversion 1.8 server will still provide the
> +          feature capabilities string, but will also provide
> +          additional information about themselves by way
> +          of <firstterm>ephemeral transaction properties</firstterm>.
> +          These are essentially commit transaction properties which

Perhaps just say "revision properties" instead of "commit txn
properties"?  i.e., avoid introducing a new term, "txnprops"; just say
"revprops that get automagically removed as the commit txn becomes
a revision".

> +          are set by the client at the earliest opportunity during the
> +          commit process, but which are then automatically removed by
> +          the server prior to the promotion of the transaction into a
> +          new revision.  You can inspect these properties using the
> +          same tools with which you'd inspect other unversioned
> +          properties set on commit transactions during the timeframe
> +          between which the start-commit and pre-commit repository
> +          hook scripts would operate.</para>


> +          <programlisting>
> +#!/bin/sh
> +
> +REPOS="$1"
> +TXN_NAME="$4"
> +
> +# Check the c

Incomplete comment.

> +CLIENT=`svnlook propget --revprop $REPOS -t $TXN_NAME svn:txn-user-agent`

Will fail silently since $PATH is empty.

> +if [ ! `echo $CLIENT | grep 'BogusSVN'` ]; then

Not a good idea.  $CLIENT is "tainted", so
    if [ ! "`printf %s "$CLIENT" | grep BogusSVN`" ]
would be better.  (But at that point you can just do
    if printf %s "$CLIENT" | grep BogusSVN > /dev/null
.)

Also, you false negative for BogusSVN/libsvn-1.7 clients: $CLIENT will
be set to empty, grep will fail, if block won't be entered.  I think
this deserves at least a code comment.  (As to fixing: one way is to
check txnprop existence, but it would be better if there were
ephemeral-txnprops capability argument to start-commit.  (if it exists,
how would pre-commit access it?  If pre-commit doesn't get capabilities,
start-commit could communicate it to pre-commit via a txnprop (and call
the txnprop svn:txn-* to have it autoremoved)))

> +        <note>
> +          <para>While most clients will transmit ephemeral transaction
> +            properties early enough in the commit process that they
> +            may be inspected by the start-commit hook script, some
> +            configurations of Subversion will cause those properties

Which configurations?  Are they server-side or client-side?  I think it
would be useful to be more specific here, even if we don't make forward
guarantees of not introducing further such situations down the road.

> +            to not be set on the transaction until later in the commit
> +            process.  Administrators should consider performing any
> +            validation based on ephemeral transaction properties in
> +            both the start-commit and pre-commit hooks—the
> +            former to rule out invalid clients before those clients
> +            transmit the commit payload; the latter <quote>just in
> +            case</quote> the validation checks couldn't be performed
> +            by the start-commit hook.</para>
> +        </note>