Author: hartmannathan
Date: Mon Feb 24 21:40:19 2020
New Revision: 1874472
URL: http://svn.apache.org/viewvc?rev=1874472&view=rev
Log:
1.14 release notes: Relative to 1.10, describe experimental changes
* docs/release-notes/1.14.html
(new-feature-compatibility-table): Add rows the experimental shelving,
commit checkpointing, and viewspec output features.
(shelving-transition,
checkpointing,
shelving,
viewspec-output): New subsections. Text is (mostly) copied from the 1.11
through 1.13 release notes, with some edits. Notably, document that while
the shelving feature can handle more types of changes than in 1.10, it is
reportedly slower than in 1.10.
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=1874472&r1=1874471&r2=1874472&view=diff
==============================================================================
--- subversion/site/publish/docs/release-notes/1.14.html (original)
+++ subversion/site/publish/docs/release-notes/1.14.html Mon Feb 24 21:40:19
2020
@@ -128,6 +128,31 @@ and what impact these changes may have.<
<td>any FSFS repo</td>
<td></td></tr>
<tr>
+ <td>
+ <a href="#shelving">Shelving (experimental)</a>
+ </td>
+ <td>1.12</td>
+ <td>any</td>
+ <td>any</td>
+ <td>shelves created by 1.10 are not compatible—see
+ <a href="#shelving-transition">the transition notes</a></td></tr>
+ <tr>
+ <td>
+ <a href="#checkpointing">Commit checkpointing (experimental)</a>
+ </td>
+ <td>1.12</td>
+ <td>any</td>
+ <td>any</td>
+ <td></td></tr>
+ <tr>
+ <td>
+ <a href="#viewspec-output">Viewspec output command (experimental)</a>
+ </td>
+ <td>1.11</td>
+ <td>any</td>
+ <td>any</td>
+ <td></td></tr>
+ <tr>
<td colspan="5"><sup>1</sup>Reminder: when using the <tt>file://</tt>
repository access method, the Subversion program is both the client
<em>and</em> the server.</td></tr>
@@ -165,6 +190,64 @@ to the upgrade.</p>
</div> <!-- wc-upgrade -->
+<div class="h3 experimental-feature" id="shelving-transition">
+<h3>Shelving (experimental): transition from 1.10
+ <a class="sectionlink" href="#shelving-transition"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>This change was first introduced in 1.11.</p>
+
+<p>Since 1.10, Subversion provides an experimental "Shelving" feature aimed
+at addressing <a href="https://issues.apache.org/jira/browse/SVN-3625";>issue
+#3625</a>.</p>
+
+<div class="notice">
+ <p><span style="color: red"><b>WARNING:</b></span> The shelving feature is
+ designated "EXPERIMENTAL" in 1.14. It is being released in an early form
+ 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>
+</div>
+
+<p>The presence in the working copy of any shelves that were created by
+Subversion 1.10 has no effect on a Subversion 1.14 client. Subversion 1.14
+will ignore them; it cannot interoperate with them nor even list their
+presence.</p>
+
+<p>The <tt>svn upgrade</tt> command has no effect, as the working copy
+format is formally unchanged.</p>
+
+<p>Shelves are currently stored under
+<tt><i><WC></i>/.svn/experimental/shelves/</tt>. In Subversion 1.10,
+shelves were stored under <tt><i><WC></i>/.svn/shelves/</tt> as patch
+files.</p>
+
+<p>To recover a shelf created by 1.10, either
+<ul><li>use a 1.10 client to find and unshelve it, or</li>
+ <li>find the patch file by hand and use any 1.10 or later
+ <tt>svn patch</tt> to apply it.</li>
+</ul></p>
+
+<p>Differences in the main shelving commands:</p>
+
+<table>
+<tr><th>Subversion 1.10 command</th>
+ <th>Subversion 1.14 equivalent</th></tr>
+<tr><td><tt>svn [x-]shelve [--keep-local] SHELF [PATH...]</tt></td>
+ <td>works similarly; saves a new version each time it is used</td></tr>
+<tr><td><tt>svn [x-]unshelve [SHELF]</tt></td>
+ <td><tt>svn x-unshelve --drop [SHELF]</tt></td></tr>
+<tr><td><tt>svn [x-]unshelve --keep-shelved [SHELF]</tt></td>
+ <td><tt>svn x-unshelve [SHELF]</tt></td></tr>
+<tr><td><tt>svn [x-]shelve --delete SHELF</tt></td>
+ <td><tt>svn x-shelf-drop SHELF</tt></td></tr>
+<tr><td><tt>svn [x-]shelves</tt> or <tt>svn [x-]shelve --list</tt></td>
+ <td><tt>svn x-shelves</tt> or <tt>svn x-shelf-list</tt></td></tr>
+</table>
+
+</div> <!-- shelving-transition -->
+
<!-- (This section only makes sense when there are some issues listed in it.)
<div class="h3" id="compat-misc">
<h3>Miscellaneous Compatibility Notes
@@ -207,6 +290,73 @@ but excluding FSFS indexes. For example:
<p>(See <a href="http://svn.apache.org/r1857624";>r1857624</a>.)</p>
</div> <!-- svnadmin-rev-size -->
+<div class="h3 experimental-feature" id="checkpointing">
+<h3>Commit checkpointing (experimental)
+ <a class="sectionlink" href="#checkpointing"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>This change was first introduced in 1.11.</p>
+
+<p>Since 1.11, Subversion provides an experimental first cut at solving some
+of the use cases envisioned in <a
+href="https://issues.apache.org/jira/browse/SVN-3626";>issue #3626</a> named
+"Commit checkpointing".</p>
+
+<div class="notice">
+ <p><span style="color: red"><b>WARNING:</b></span> The checkpointing feature
+ is designated "EXPERIMENTAL" in 1.11. It is being released in an early form
+ while development continues. It is expected to change significantly during
+ and after the 1.11.x series. There is no promise of backward compatibility
+ while it remains experimental.</p>
+</div>
+
+<p>It provides the ability to save a snapshot of an uncommitted change from
+time to time, and later restore one of those previous versions of your
+change back into the working copy.</p>
+
+<p>It does not provide the kind of exact WC state roll back that is also
+discussed in that issue, that could make it possible after a messy update to
+roll back to the exact WC state that existed just before. This remains a
+future possibility.</p>
+
+<p>The ability to checkpoint and roll back an uncommitted change is provided
+within the shelving feature, by letting a shelf hold multiple versions of
+your change. Therefore, see also <a href="#shelving"> Shelving</a>.</p>
+
+<p>The main checkpointing operations are accomplished by the following
+commands, as also listed in
+<a href="https://cwiki.apache.org/confluence/x/70cYBQ";>the Wiki page</a>:</p>
+
+<table>
+<tr><th>Save a checkpoint and continue</th>
+ <td><tt>svn x-<b>shelf-save</b> foo</tt></td>
+ <td>copy the local changes into a new version of shelf 'foo';<br/>
+ doesn't revert the changes from the WC</td>
+</tr>
+<tr><th>Save a checkpoint and shelve</th>
+ <td><tt>svn x-<b>shelve</b> foo</tt></td>
+ <td>move the local changes into a new version of shelf 'foo'<br/>
+ and revert the changes from the WC</td>
+</tr>
+<tr><th>Restore / roll back</th>
+ <td>first revert your unwanted changes; then<br/>
+ <tt>svn x-<b>unshelve</b> foo 3</tt></td>
+ <td>apply version 3 of shelf 'foo' to the WC<br/>
+ and delete any newer versions</td>
+</tr>
+<tr><th>Review checkpoints</th>
+ <td><tt>svn x-<b>shelf-log</b> foo</tt></td>
+ <td>list all the versions of shelf 'foo'</td>
+</tr>
+<tr><th></th>
+ <td><tt>svn x-<b>shelf-diff</b> foo 3</tt></td>
+ <td>show version 3 as a diff</td>
+</tr>
+</table>
+
+</div> <!-- checkpointing -->
+
</div> <!-- new-features -->
<div class="h2" id="enhancements">
@@ -419,6 +569,113 @@ not use, but which introduces more I/O w
</div> <!-- sqlite-omit-wal -->
+<div class="h4 experimental-feature" id="shelving">
+<h4>Improved Shelving (experimental)
+ <a class="sectionlink" href="#shelving"
+ 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>
+
+<div class="notice">
+ <p><span style="color: red"><b>WARNING:</b></span> The shelving feature is
+ designated "EXPERIMENTAL" in 1.14. It is being released in an early form
+ 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>
+</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>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>
+<ul>
+ <li>checkpointing support: a shelf stores multiple versions of a
+ change; shelving adds a new version to the named shelf; you can
+ unshelve an older version instead of the newest—see the
+ <a href="#checkpointing">checkpointing</a> feature</li>
+ <li>'binary' files (and property values) are fully supported</li>
+ <li>patch files are no longer used as the storage mechanism;
+ limitations and bugs due to patch file format are gone, such as
+ handling svn:mergeinfo properties, binary data, and end-of-line
+ characters</li>
+ <li>shelving and unshelving both warn and refuse to run if they detect
+ states that they cannot handle (e.g. copies or moves)</li>
+ <li>unshelving applies the changes to the WC using a mechanism similar
+ to merging, so that changes can be more robustly applied when the
+ 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>
+<ul>
+ <li>copies and moves</li>
+ <li>creating and deleting directories</li>
+</ul>
+
+<p>Shelving commands (see their help for details):</p>
+<ul>
+ <li><tt>svn x-shelf-diff</tt></li>
+ <li><tt>svn x-shelf-drop</tt></li>
+ <li><tt>svn x-shelf-list, x-shelves</tt></li>
+ <li><tt>svn x-shelf-list-by-paths</tt></li>
+ <li><tt>svn x-shelf-log</tt></li>
+ <li><tt>svn x-shelf-save</tt></li>
+ <li><tt>svn x-shelve</tt></li>
+ <li><tt>svn x-unshelve</tt></li>
+</ul>
+
+<p>Further information can be found in the Subversion Wiki under
+<a
href="https://cwiki.apache.org/confluence/display/SVN/Shelving+and+Checkpointing";>Shelving
and Checkpointing</a>.
+</p>
+
+</div> <!-- shelving -->
+
+<div class="h4 experimental-feature" id="viewspec-output">
+<h4>Viewspec output command (experimental)
+ (<a href="https://issues.apache.org/jira/browse/SVN-4753";>issue #4753</a>)
+ <a class="sectionlink" href="#viewspec-output"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>This change was first introduced in 1.11.</p>
+
+<p>There is an experimental command to write out a view spec describing the
+current WC shape.</p>
+
+<div class="notice">
+ <p><span style="color: red"><b>WARNING:</b></span> This feature
+ is designated "EXPERIMENTAL" in 1.14. It is being released in an early form
+ 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>
+</div>
+
+<p>A view spec describes whether each subtree is at a limited depth, excluded,
+switched to a different URL, or updated to a different revision number,
+compared with its parent directory. This information is sometimes referred
+to as the shape or the layout of a WC.</p>
+
+<p>'<tt>svn info --x-viewspec=classic</tt>' writes in the format used by the
old script
+<a
href="http://svn.apache.org/viewvc/subversion/trunk/tools/client-side/svn-viewspec.py";>tools/client-side/svn-viewspec.py</a>.</p>
+
+<p>'<tt>svn info --x-viewspec=svn11</tt>' writes a series of '<tt>svn</tt>'
+command lines. You can create a new WC of the same layout by running these
+commands.</p>
+
+</div> <!-- viewspec-output -->
+
</div> <!-- cmdline -->
<div class="h3" id="server-side-improvements">
