subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hartmannat...@apache.org
Subject svn commit: r1875127 - /subversion/site/publish/docs/release-notes/1.14.html
Date Thu, 12 Mar 2020 15:15:43 GMT
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">&para;</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>



Mime
View raw message