Update release notes

1 files changed, 285 insertions, 43 deletions

diff --git a/debian/svn_1.9_releasenotes.html b/debian/svn_1.9_releasenotes.html
index 8c57483..03dbcf6 100644
--- a/debian/svn_1.9_releasenotes.html
+++ b/debian/svn_1.9_releasenotes.html
@@ -172,6 +172,7 @@ and cannot be fixed even if <tt>svn cleanup</tt> is run prior to the upgrade.</p
 
 </div>  <!-- wc-upgrade -->
 
+<!--
 <div class="h3" id="output-changes">
 <h3>Command Line Output Changes
   <a class="sectionlink" href="#output-changes"
@@ -185,7 +186,7 @@ output.  For this reason, we encourage programs which consume the output
 of the commandline client to consider using the <tt>--xml</tt> option,
 or accessing Subversion through the various bindings interfaces.</p>
 
-<!-- Insert items here, of the following form:
+### Insert items here, of the following form:
 <div class="h4" id="foo">
 <h4>Improved output of <tt>svn foo</tt>
   <a class="sectionlink" href="#foo"
@@ -205,17 +206,6 @@ example illustrates these changes.</p>
 </pre>
 
 </div>
--->
-
-<div class="h4" id="annoying-formatting">
-<h4>### Annoying formatting
-  <a class="sectionlink" href="#annoying-formatting"
-    title="Link to this section">&para;</a>
-</h4>
-
-<p><span style="color: red"><i>### All output is now centred.</i></span></p>
-
-</div>  <!-- annoying-formatting -->
 
 </div>  <!-- output-changes -->
 
@@ -366,7 +356,7 @@ the benefits.
 <table border="1">
   <tr>
     <th>Feature</th>
-    <th>Format 6 (SVN 1.8)<br />or older</th>
+    <th>Format 6<br />or older</th>
     <th>Upgraded to format 7<br />from older formats</th>
     <th>Created as format 7<br />not packed</th>
     <th>Created as format 7<br />packed</th>
@@ -579,7 +569,10 @@ means more net speed, some changes may affect your configuration settings.</p>
     title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
+<p>Where the <tt>svnadmin</tt> tool covers typical administrative tasks
+in a mostly back-end agnostic way, <tt>svnfsfs</tt> is a specialist tool
+for analyzing and manipulating of FSFS repositories.  It is not intended
+for everyday use.
 </p>
 
 </div>  <!-- svnfsfs-overview -->
@@ -590,7 +583,9 @@ means more net speed, some changes may affect your configuration settings.</p>
     title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
+<p>The <tt>fsfs-stats</tt> tool first released with Subversion 1.8 has
+been replaced by the <tt>svnfsfs stats</tt> sub-command and is no longer
+part of Subversion 1.9.  Both produce similar output.
 </p>
 
 </div>  <!-- svnfsfs-stats -->
@@ -601,9 +596,36 @@ means more net speed, some changes may affect your configuration settings.</p>
     title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
+<p>During forensics or data recovery, it is necessary for experts to
+directly "look into" the raw database files.  While the FSFS on-disk
+format is fully documented, the indirect addressing and reordering
+added in format 7 makes it hard for humans to trace internal references.
+This is where the <tt>svnfsfs dump-index</tt> sub-command is used.
+It produces a table describing all items in revision and pack files:
 </p>
 
+<pre>
+    $ svnfsfs dump-index /path/to/repo -r0
+       Start       Length Type   Revision     Item Checksum
+           0           11 drep          0        3 60232b75
+          11           59 node          0        2 403dbe48
+          6a            1 chgs          0        1 f28a4f1d
+</pre>
+
+<p>Because the index information must always match the actual file
+contents, updating the index data after every revision / pack file
+manipulation is mandatory in format 7. <tt>svnfsfs load-index</tt>
+allows you to do that.  It consumes the same table format as produced
+above, except that the checksum field is optional and will be ignored
+if given.
+</p>
+
+<div class="notice">
+  <p><span style="color: red"><b>WARNING:</b></span> Be sure to
+    create a backup of your repository before trying to manipulate
+    it through <tt>svnfsfs</tt> !</p>
+</div>
+
 </div>  <!-- svnfsfs-index-manipulation -->
 
 </div>  <!-- svnfsfs -->
@@ -734,8 +756,36 @@ support reading or writing FSX repositories.</p>
      title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
+<p>The new <tt>svn auth</tt> sub-command can be used to view or remove
+authentication credentials saved in any of the supported password caches.
+Authentication credentials include usernames, passwords,
+SSL certificates, and SSL client-certificate passphrases.</p>
+
+<p>Specific credentials can be selected with an arbitrary number of pattern
+arguments which are matched against the attributes of each credential.
+For example, view cached SSL certificates for the <i>apache.org</i> domain,
+matched via credential kind (svn.ssl.server) and authentication realm and
+certificate subject (apache.org):
 </p>
+<pre>
+$ svn auth svn.ssl.server apache.org
+------------------------------------------------------------------------
+Credential kind: svn.ssl.server
+Authentication realm: https://svn.us.apache.org:443
+Subject: C=US, ST=Maryland, L=Forest Hill, O=The Apache Software Foundation, OU=Infrastructure, CN=*.apache.org
+Valid from: 2015-04-29 02:00:00 +0200 (Wed, 29 Apr 2015)
+Valid until: 2017-04-30 01:59:59 +0200 (Sun, 30 Apr 2017)
+Issuer: C=US, O=Symantec Corporation, OU=Symantec Trust Network, CN=Symantec Class 3 Secure Server CA - G4
+Fingerprint: 4ad722dd0442043657d176f9c81aab66094d4223
+Hostnames: *.apache.org
+Automatic certificate validity check failed because:
+  The certificate's Common Name (hostname) does not match the remote hostname.
+
+  Credentials cache in '~/.subversion' contains 1 matching credentials
+</pre>
+
+<p>For more information, see <tt>svn help auth</tt>.</p>
+
 </div> <!-- svn-auth -->
 
 <div class="h4" id="svn-info-item">
@@ -744,8 +794,49 @@ support reading or writing FSX repositories.</p>
      title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
-</p>
+<p>The <tt>svn info</tt> command can now display the value of one of the fields
+and nothing else, for easier consumption by scripts.</p>
+
+<p>Subversion 1.8 and earlier had two output modes: the default, human-oriented
+output, mode and the XML mode for scripted use.  Subversion 1.9 adds a third
+output mode, whereby exactly one attribute will be displayed:</p>
+
+<pre>
+## Display the youngest revision of a repository:
+% svn info --show-item=revision https://svn.apache.org/repos/asf/subversion/trunk
+1693514
+
+## Find the root directory of a working copy:
+% svn info --show-item=wc-root
+/home/jrandom/src/svn/trunk
+</pre>
+
+<p>Incidentally, Subversion will also attempt to offer the correct selector name
+if the argument was misspelled:</p>
+
+<pre>
+% svn info --show-item=wcroot
+svn: E205000: Try 'svn help info' for more information
+svn: E205000: 'wcroot' is not a valid value for --show-item; did you mean 'wc-root'?
+</pre>
+
+<p>The list of valid arguments to <tt>--show-item</tt> may be found in its help
+message, <tt>svn help info</tt>.  As of 1.9, the valid values are
+<tt>kind</tt>,
+<tt>url</tt>,
+<tt>relative-url</tt>,
+<tt>repos-root-url</tt>,
+<tt>repos-uuid</tt>,
+<tt>revision</tt>,
+<tt>last-changed-revision</tt>,
+<tt>last-changed-date</tt>,
+<tt>last-changed-author</tt>,
+and
+<tt>wc-root</tt>.</p>
+
+<p>The <tt>--no-newline</tt> argument instructs <tt>svn</tt>
+not to emit a cosmetic newline (<tt>\n</tt>) after the value.</p>
+
 </div> <!-- svn-info-item -->
 
 <div class="h4" id="svn-propget-no-newline">
@@ -754,8 +845,9 @@ support reading or writing FSX repositories.</p>
      title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
-</p>
+<p>The <tt>svn propget</tt> sub-command has a new <tt>--no-newline</tt> option.
+It is equivalent to the old <tt>--strict</tt> option which is now deprecated.</p>
+
 </div> <!-- svn-propget-no-newline -->
 
 <div class="h4" id="svn-trust">
@@ -764,10 +856,54 @@ support reading or writing FSX repositories.</p>
      title="Link to this section">&para;</a>
 </h4>
 
-<p>### TODO
-</p>
+<p>The new <tt>--trust-server-cert-failures</tt> option is intended to be used
+by scripts which for some reason must accept SSL certificates which fail
+validation for various reasons (e.g. expired certificates).</p>
+
+<p>If at all possible, fixing a certificate problem is preferable to using
+this option.</p>
+
+<p>The <tt>--trust-server-cert-failures</tt> option only works in conjunction with
+the <tt>--no-interactive</tt> option.</p>
+
+<p>Previous versions of Subversion in non-interactive mode could only ignore
+certificates with an unknown certificate authority, but expired or otherwise
+invalid SSL certificates could not be accepted.</p>
+
 </div> <!-- svn-trust -->
 
+<div class="h4" id="svn-copy-pin-externals">
+<h4>New <tt>--pin-externals</tt> option for <tt>svn copy</tt>
+  <a class="sectionlink" href="#svn-copy-pin-externals"
+     title="Link to this section">&para;</a>
+</h4>
+
+<p>The <tt>svn copy</tt> sub-command now supports a new <tt>--pin-externals</tt> option.
+Use of this option is recommended when creating tags.</p>
+
+<p>If this option is used, <tt>svn copy</tt> pins the URLs in <tt>svn:externals</tt>
+properties in the copied tree to their current revision, such that externals keep
+their current contents when the copied tree is checked out at a later time.</p>
+
+<p>Note that external references within externals cannot be pinned as this would require
+<tt>svn copy</tt> to make commits to any foreign repositories referenced by externals.</p>
+
+</div> <!-- svn-copy-pin-externals -->
+
+<div class="h4" id="svn-cleanup-options">
+<h4>New options for <tt>svn cleanup</tt>
+  <a class="sectionlink" href="#svn-cleanup-options"
+     title="Link to this section">&para;</a>
+</h4>
+
+<p>The <tt>svn cleanup</tt> command has new <tt>--remove-unversioned</tt>
+and <tt>--remove-ignored</tt> options which can be used to remove unversioned
+and ignored files from the working copy.</p>
+
+<p><tt>svn cleanup</tt> can now recurse into externals with the new
+<tt>--include-externals</tt> option.</p>
+
+</div> <!-- svn-cleanup-options-->
 
 <div class="h4" id="svn-resolver-m">
 <h4>Interactive conflict resolver changes
@@ -775,15 +911,89 @@ support reading or writing FSX repositories.</p>
      title="Link to this section">&para;</a>
 </h4>
 
-<p class="todo">The 'm' command now tries the external merge tool if it is
-defined, else the internal diff3 implementation.  In 1.8 it always used the
-internal diff3.  The 'i' command was added with the old meaning of the 'm'
+<p>In the interactive conflict resolver, the <tt>(m) merge</tt> command now
+tries an external file merge tool if one is defined. Else the internal file
+merge tool is used.</p>
+
+<p>In Subversion 1.8, the <tt>(m) merge</tt> command always triggered the
+internal file merge tool. The <tt>(i) internal merge tool</tt> command was
+added to Subversion 1.9 and has the old meaning of the <tt>(m) merge</tt>
 command.</p>
 
 </div> <!-- svn-resolver-m -->
 
 </div> <!-- cmdline -->
 
+<div class="h3" id="server-side-improvements">
+<h3>Server-side improvements
+  <a class="sectionlink" href="#server-side-improvements"
+     title="Link to this section">&para;</a>
+</h3>
+
+<div class="h4" id="fewer-ood-conditions">
+<h4>Committing the result of large merges
+  <a class="sectionlink" href="#fewer-ood-conditions"
+     title="Link to this section">&para;</a>
+</h4>
+
+<p>Our best practices suggest that projects should branch and merge
+at the project root level.  Each merge will then usually change the
+<tt>svn:mergeinfo</tt> property at the project base folder.  To commit
+that change, pre-1.9 servers require the client to have the latest
+version of that base folder.  Whenever there is a commit in that tree,
+its base folder will get a new revision as well, though.   Thus, in
+large, busy projects, it is likely that by the time a large merge commit
+would actually have reached its finalization phase, some other commit
+got through and the merge commit is rejected for being out of date.  
+</p>
+
+<p>Subversion 1.9 now allows to modify directory properties based on
+old revisions as long as the directory contents itself did no change.
+Directory contents changes would either be property changes,  added or
+removed entries.  Sub-tree or file contents changes no longer prevent
+the property change from going through.  Of course, true file and tree
+change conflicts will still result in out-of-date errors.
+</p>
+
+<p>This new behavior is not restricted to <tt>svn:mergeinfo</tt> changes
+but applies to any directory properties.  Changes to <tt>svn:ignore</tt>
+are another common scenario previously prone to update / commit /
+out-of-date races.
+</p>
+
+</div> <!-- fewer-ood-conditions -->
+
+<div class="h4" id="rate-limiting-svnserve">
+<h4>Rate limiting <tt>svnserve</tt>
+  <a class="sectionlink" href="#rate-limiting-svnserve"
+     title="Link to this section">&para;</a>
+</h4>
+
+<p>In threaded mode, <tt>svnserve</tt> starts one thread per network
+connection - potentially consuming a large amount of resources.
+Subversion 1.9 now uses a thread pool with a configurable minimum and
+maximum number of threads.  Use the command line options
+<tt>--min-threads</tt> and <tt>--max-threads</tt> if the defaults
+don't suite your needs.
+</p>
+  
+<div class="notice">
+  <p>Once there are more connections than threads, the threads will serve
+  incoming requests in a round-robin fashion.  If all those requests are
+  long-running reports like checkout or export, connections with waiting
+  requests may eventually time out.</p>
+</div>
+
+<p>Whether or not the new options are available depends on the platform
+and APR capabilities.  Also, the default for <tt>--max-threads</tt> is
+lower on 32 bit systems than on 64 bit ones.  Run <tt>svnserve --help</tt>
+to see your system's defaults and whether the options are available at all.
+</p>
+  
+</div> <!-- rate-limiting-svnserve -->
+
+</div> <!-- server-side-improvements -->
+
 <div class="h3" id="svnadmin-improvements">
 <h3><tt>svnadmin</tt> changes and improvements
   <a class="sectionlink" href="#svnadmin-improvements"
@@ -855,19 +1065,21 @@ revision such that multiple issues may be found in a single run.  If a revision
 has multiple issues and depending on the verification logic, still only the
 first problem may be reported.</p>
 
-<p>Thorough verification is expensive and will gets slower as the repository
-history grows.  FSFS format 7 repositories not only protect the reconstructed
-user data with checksums but also the deltified on-disk representation.  The
-new <tt>--metadata-only</tt> flag will skip the expensive internal consistency
-checks and reconstruction of all user data.</p>
+<p>The new <tt>--check-normalization</tt> option reports any path names
+within the same directory or svn:mergeinfo property which differ only
+in character representation (e.g. Unicode precomposed and decomposed
+character representations), but are otherwise identical.</p>
 
-<p>In format 7 repositories, this will still perform a quick on-disk checksum
-test of everything data in rev / pack files but will only detect cases where
+<p>Thorough verification is expensive and becomes slower as the repository
+history grows.  The new <tt>--metadata-only</tt> flag will skip the expensive
+internal consistency checks and reconstruction of all user data.
+In format 7 repositories, this will still perform a quick on-disk checksum
+test of all data in rev / pack files but will only detect cases where
 external forces (storage crash, rogue scripts etc.) modified committed data.
 Also, the checksums are weaker (about a 1 in a billion chance that a random
 change remains undetected) than the ones used to protect the user data.  If
-you suspect internal repository corruption such as caused by a bug within SVN
-itself, you still need to run a full verification.</p>
+you suspect internal repository corruption caused by a bug within SVN itself,
+you still need to run a full verification.</p>
 
 </div>  <!-- svnadmin-verify -->
 
@@ -1009,8 +1221,8 @@ will be.</p>
 <p>For example, to see for each line in revision&nbsp;3 of README.txt what the
 next revision that changed (or removed) that line would be, run
 <tt>svn blame -r HEAD:3 README.txt</tt>.  (You may need to pass a
-<!-- TODO: link is broken (no 1.9 book branch yet) -->
-<a href="http://svnbook.red-bean.com/en/1.9/svn.advanced.pegrevs.html">peg
+<!-- TODO: link points to nightly (no 1.9 book branch yet) -->
+<a href="http://svnbook.red-bean.com/nightly/en/svn.advanced.pegrevs.html">peg
 revision</a> if the file had been renamed since r3.)</p>
 
 <p>In the <tt>blame</tt> command, the range <tt>-r&nbsp;M:N</tt> always means
@@ -1020,7 +1232,21 @@ line in the file when it was added or last changed; if the range is "reversed"
 (M&gt;N) then the above-described sense is used, describing for each line in rN
 when it was first changed (or deleted) after rN and before rM.</p>
 
-<p class="todo">Add example</p>
+<p>Here is an example, from Subversion's own repository.  The autoconf macro
+<tt>SVN_CHECK_FOR_DUNDER_BUILTINS</tt> was
+<a href="https://svn.apache.org/viewvc/subversion/trunk/build/ac-macros/svn-macros.m4?view=markup&amp;pathrev=1509167#l167"
+>present in r1509167</a> but is not present in HEAD.  The <tt>blame</tt>
+command can determine the revision in which the macro was removed:</p>
+
+<pre>
+% svn blame -r HEAD:1509167 svn-macros.m4
+&vellip;
+1509168   danielsh AC_DEFUN([SVN_CHECK_FOR_DUNDER_BUILTINS],
+</pre>
+
+<p>And indeed, <tt>svn diff -c r1509168</tt> shows that revision 
+<a href="https://svn.apache.org/viewvc/subversion/trunk/build/ac-macros/svn-macros.m4?r1=1509168&amp;r2=1509167&amp;pathrev=1509168&amp;diff_format=h"
+>deleting the definition of the macro</a>.</p>
 
 </div> <!-- prospective-blame -->
 
@@ -1035,15 +1261,31 @@ when it was first changed (or deleted) after rN and before rM.</p>
 <p>There are some known issues in the Subversion 1.9 releases.  These
 may be fixed in later 1.9.x releases.</p>
 
-<div class="h3" id="1234-bad-stuff">
-<h3>### Stuff is broken
-  <a class="sectionlink" href="#1234-bad-stuff"
+<div class="h3" id="httpv1-commit-race">
+<h3>"Out of date" errors when committing over HTTPv1
+  <a class="sectionlink" href="#httpv1-commit-race"
     title="Link to this section">&para;</a>
 </h3>
 
-<p><span style="color: red"><i>### SVN 1.9.0 has broken code in it.</i></span></p>
+<p>If there are concurrent commits to the same repository, they may
+randomly fail with an "out of date" error message without actually
+being in conflict.  The problem presents itself to the user like any
+legitimate out-of-date condition and retrying the commit as usual
+will fix the problem.
+</p>
+
+<p>This problem is not new to Subversion 1.9 and limited to repositories
+with high commit frequencies.  Triggering it requires either pre-1.7
+clients, a pre-1.7 server or a server that has HTTPv2 explicitly disabled
+via the <tt>SVNAdvertiseV2Protocol off</tt> option.  To avoid the problem,
+consider upgrading clients and configuring the server to use the HTTPv2
+protocol.
+</p>
+
+<p>svnserve and local repository access are not affected.
+</p>
 
-</div>  <!-- 1234-bad-stuff -->
+</div>  <!-- httpv1-commit-race -->
 
 </div>  <!-- issues -->