subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cmpil...@apache.org
Subject svn commit: r1392580 - /subversion/site/publish/docs/release-notes/1.8.html
Date Mon, 01 Oct 2012 20:42:04 GMT
Author: cmpilato
Date: Mon Oct  1 20:42:04 2012
New Revision: 1392580

URL: http://svn.apache.org/viewvc?rev=1392580&view=rev
Log:
* site/publish/docs/release-notes/1.8.html
  First pass at documenting the changes to the start-commit hook
  invocation time and the ephemeral transaction properties stuff.

Modified:
    subversion/site/publish/docs/release-notes/1.8.html

Modified: subversion/site/publish/docs/release-notes/1.8.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/release-notes/1.8.html?rev=1392580&r1=1392579&r2=1392580&view=diff
==============================================================================
--- subversion/site/publish/docs/release-notes/1.8.html (original)
+++ subversion/site/publish/docs/release-notes/1.8.html Mon Oct  1 20:42:04 2012
@@ -1001,6 +1001,62 @@ a UTF-8 locale using the <a href="#hooks
 
 </div>  <!-- mod-dav-svn -->
 
+<div class="h4" id="hooks-start-commit">
+<h4><tt>start-commit</tt> hook invocation point changed
+  <a class="sectionlink" href="#hooks-start-commit"
+    title="Link to this section">&para;</a>
+</h4>
+
+<p>Prior to this release, the <tt>start-commit</tt> hook script was
+invoked by Subversion just prior to the creation of the commit
+transaction.  An errorful return from the hook would be marshaled back
+to the client without the commit transaction having ever been created.
+A successful return would permit the creation of the commit
+transaction, and allow the commit process to proceed as expected.
+Administrators generally employed the <tt>start-commit</tt> hook to
+immediately deny <em>all</em> commits to a repository, as the amount
+of information available to the hook by which to do so
+<em>conditionally</em> was pretty slim.</p>
+
+<p>Beginning with Subversion 1.8, the <tt>start-commit</tt> hook is
+invoked immediately <em>after</em> Subversion creates the commit
+transaction and sets its initial properties.  This
+allows <tt>start-commit</tt> implementations to examine the commit
+transaction's properties (such as the revision log message and the new
+<a href="#ephemeral-txnprops">ephemeral transaction properties</a>)
+when deciding whether or not to allow the commit to proceed.
+Subversion will abort the created transaction upon detecting an
+errorful return from the hook and will, of course, still marshal that
+error condition back to the client.</p>
+
+<p>This change empowers administrators to disallow certain commits via
+the <tt>start-commit</tt> hook rather than doing so much later &mdash;
+after the client's changes are transmitted across the network &mdash;
+in the <tt>pre-commit</tt> hook.  Imagine the frustration of a user
+who has endured the lengthy upload of 2 Gb of commit data only to have
+his or her commit bounced because of an insufficiently formatted log
+message!  These changes to <tt>start-commit</tt> allow the go/no-go
+decision on such a commit to be made before that large commit payload
+is transmitted across the wire.</p>
+
+<p><strong>Note:</strong> Subversion does not require that commit
+transaction properties (such as the revision log message) be attached
+to the transaction as part of its initialization.  As such, some
+clients will still not provide that information to the server until
+after the <tt>start-commit</tt> hook has been invoked.  Here is a list
+of such clients we are aware of:</p>
+
+<ul>
+<li>Pre-1.8 clients communicating via HTTP</li>
+<li>Clients communicating via HTTP when mod_dav_svn's
+    "SVNAdvertiseV2Protocol" option has been set to "off"</li>
+</ul>
+
+<p>Administrators should consider modularizing the tests that their
+hooks perform on transaction properties, invoke those tests from both
+the <tt>start-commit</tt> and <tt>pre-commit</tt> hook scripts.</p>
+
+</div>  <!-- hooks-start-commit -->
 
 <div class="h4" id="hooks-post-commit">
 <h4><tt>post-commit</tt> hook grows <tt>txn-name</tt> argument
@@ -1026,6 +1082,49 @@ itself.</p>
 
 </div>  <!-- hooks-post-commit -->
 
+<div class="h4" id="ephemeral-txnprops">
+<h4>Commit transactions now carry client information
+  <a class="sectionlink" href="#ephemeral-txnprops"
+    title="Link to this section">&para;</a>
+</h4>
+
+<p>Subversion 1.8 clients communicating to 1.8 servers
+(via <tt>http[s]:</tt> or <tt>svn:</tt>) will now attach "ephemeral
+transaction properties" to commit transactions which carry metadata
+considered useful to server-side hook scripts.  These special
+properties are set on the commit transaction as early as possible
+(generally prior to the invocation of
+the <a href="#hooks-start-commit"><tt>start-commit</tt></a> hook,
but
+certainly prior to the invocation of the <tt>pre-commit</tt> hook),
+and then automatically removed by Subversion just prior to the commit
+transaction being promoted to a new revision.</p>
+
+<p>Currently, the following ephemeral transaction properties are
+available to hook scripts for examination:</p>
+
+<ul>
+<li><strong>svn:txn-user-agent</strong> - carries the "user agent"
+    string which describes the committing client program.  (Developers
+    of third-party clients which link against the Subversion libraries
+    may modify the customizable portion of this string by implementing
+    the <tt>get_client_string()</tt> RA callback API which was
+    introduced in Subversion 1.5.)</li>
+<li><strong>svn:txn-client-compat-version</strong> - carries the
+    Subversion library version string with which the connecting client
+    claims compatibility.</li>
+</ul>
+
+<p><strong>Note:</strong> Administrators who deem the information
+carried in these properties to be of long-term value may of course log
+the information as they see fit.  For example, such an administrator
+may wish to modify his or her <tt>pre-commit</tt> hook script to copy
+the values of those properties to new, custom transaction properties
+(which do <em>not</em> have names within the reserved <tt>svn:</tt>
+namespace, of course!)  for long-term storage associated with the
+commit.</p>
+
+</div>  <!-- ephemeral-txnprops -->
+
 </div>  <!-- hooks -->
 
 <div class="h3" id="svnpubsub">



Mime
View raw message