Author: hartmannathan
Date: Thu Mar 12 15:15:43 2020
New Revision: 1875127
URL: http://svn.apache.org/viewvc?rev=1875127&view=rev
Log:
1.14 release notes: Document selectable shelving implementation
* docs/release-notes/1.14.html
(shelving): Document that users can select between Shelving-v2 and
Shelving-v3 via the SVN_EXPERIMENTAL_COMMANDS environment
variable, as introduced in r1875037.
Modified:
subversion/site/publish/docs/release-notes/1.14.html
Modified: subversion/site/publish/docs/release-notes/1.14.html
URL:
http://svn.apache.org/viewvc/subversion/site/publish/docs/release-notes/1.14.html?rev=1875127&r1=1875126&r2=1875127&view=diff
==============================================================================
--- subversion/site/publish/docs/release-notes/1.14.html (original)
+++ subversion/site/publish/docs/release-notes/1.14.html Thu Mar 12 15:15:43
2020
@@ -575,11 +575,9 @@ not use, but which introduces more I/O w
title="Link to this section">¶</a>
</h4>
-<p>This change was first introduced in 1.11.</p>
-
<p>Shelving (<a href="https://issues.apache.org/jira/browse/SVN-3625";>issue
-#3625</a>), first introduced in Subversion 1.10, is improved to handle more
-kinds of changes more robustly.</p>
+#3625</a>), first introduced in Subversion 1.10, has been developed further to
+handle more kinds of changes more robustly.</p>
<div class="notice">
<p><span style="color: red"><b>WARNING:</b></span> The shelving feature is
@@ -587,19 +585,47 @@ kinds of changes more robustly.</p>
while development continues. It is expected to change significantly during
and after the 1.14.x series. There is no promise of backward compatibility
while it remains experimental.</p>
+
+ <p>Shelving in 1.14 is incompatible with shelves created by 1.10. See
+ <a href="#shelving-transition">the transition notes</a> on recovering 1.10
+ shelves and differences in commands.</p>
</div>
-<div class="notice">
- <p>While the shelving feature in 1.14 can handle more kinds of changes than
- that in 1.10, some users have reported that it performs much more slowly,
- especially when used with large working copies.</p>
-</div>
+<p>Subversion 1.14 offers two different shelving CLI implementations,
+selectable by an environment variable (see
+<a href="http://svn.apache.org/r1875037";>r1875037</a>.) These are
+"Shelving-v2" as introduced in 1.11, and "Shelving-v3" as introduced in 1.12.
+The two implementations are incompatible with each other, but both are offered
+because they have substantially different pros and cons.</p>
+
+<p>The shelving CLI implementation is selected by an environment variable,
+<tt>SVN_EXPERIMENTAL_COMMANDS</tt>, as follows:</p>
+
+<table border="1">
+ <tr>
+ <th>environment variable</th>
+ <th>shelving CLI implementation</th>
+ </tr>
+ <tr>
+ <td>Environment variable not set</td>
+ <td>Shelving-v3, as introduced in 1.12</td>
+ </tr>
+ <tr>
+ <td><tt>SVN_EXPERIMENTAL_COMMANDS=shelf3</tt></td>
+ <td>Shelving-v3, as introduced in 1.12</td>
+ </tr>
+ <tr>
+ <td><tt>SVN_EXPERIMENTAL_COMMANDS=shelf2</tt></td>
+ <td>Shelving-v2, as introduced in 1.11</td>
+ </tr>
+ <tr>
+ <td><tt>SVN_EXPERIMENTAL_COMMANDS=</tt></td>
+ <td>No shelving CLI</td>
+ </tr>
+</table>
-<p>Shelving in 1.14 is incompatible with shelves created by 1.10. See
-<a href="#shelving-transition">the transition notes</a> on recovering 1.10
-shelves and differences in commands.</p>
-
-<p>The main improvements and changes are:</p>
+<p>Shelving-v2, first introduced in 1.11, improves upon the initial shelving
+feature introduced in 1.10. The main improvements and changes are:</p>
<ul>
<li>checkpointing support: a shelf stores multiple versions of a
change; shelving adds a new version to the named shelf; you can
@@ -617,13 +643,59 @@ shelves and differences in commands.</p>
WC has been modified (e.g. updated) since the shelf was saved</li>
</ul>
-<p>The kinds of change you can shelve are committable changes to files and
-properties, except the following kinds which are not yet supported:</p>
+<p>Shelving-v2 can shelve committable changes to files and properties, except
+the following kinds which it does not support:</p>
<ul>
<li>copies and moves</li>
<li>creating and deleting directories</li>
</ul>
+<p>Shelving-v3, first introduced in 1.12, can handle more kinds of changes
+than Shelving-v2. In particular, it supports shelving of all committable
+changes. However, it performs much more slowly than Shelving-v2 and uses more
+disk space, especially when used with large working copies.</p>
+
+<p>The following table summarizes the kinds of changes that can be shelved by
+the two implementations:</p>
+
+<table border="1">
+ <tr>
+ <th>WC State or Change</th>
+ <th>Shelving-v2</th>
+ <th>Shelving-v3</th>
+ </tr>
+ <tr>
+ <td>file text, file delete/add, most properties</td>
+ <td>yes</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td>mergeinfo changes</td>
+ <td>yes</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td>copies and moves</td>
+ <td>no</td>
+ <td>as copies<sup>1</sup></td>
+ </tr>
+ <tr>
+ <td>directories (mkdir/rmdir/...)</td>
+ <td>no</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td>binary files & properties</td>
+ <td>yes</td>
+ <td>yes</td>
+ </tr>
+ <tr>
+ <td colspan="3"><sup>1</sup>On shelving, a move is converted to
+ copy-and-delete, just like it is on commit.
+ </td>
+ </tr>
+</table>
+
<p>Shelving commands (see their help for details):</p>
<ul>
<li><tt>svn x-shelf-diff</tt></li>
