Author: hartmannathan Date: Sun Mar 15 21:35:15 2020 New Revision: 1875216 URL: http://svn.apache.org/viewvc?rev=1875216&view=rev Log: 1.14 release notes: Refactor to put all experimental features in one area
Instead of scattering text about experimental features all over the release notes, create a new h2 section, "Experimental Features," and consolidate all such subsections there. In particular, consolidate all sections related to shelving and checkpointing, as a single subsection of Experimental Features. This refactoring has the side benefit of eliminating numerous yellow "Warning" boxes scattered throughout. Now there is just one such box at the beginning of the Experimental Features section. This refactoring incorporates some of the suggestions made by danielsh in dev@ thread "Re: svn commit: r1875127..." on 2020/03/12, archived here: https://lists.apache.org/thread.html/re39d729b04cdc6eae1cdb6cb3c0db85b2252b97f05b0fd55b0109a45%40%3Cdev.subversion.apache.org%3E * docs/release-notes/1.14.html (compatibility-shelving): New subsection, replacing #shelving-transition with much shorter text and links to consolidated shelving section. (experimental): New h2 section to contain all experimental feature and API subsections. (shelving): Promote from h4 to h3 per danielsh's suggestion and place within experimental. Collect all shelving and checkpointing related text here and rearrange for improved flow. (shelving-enabling, shelving-v2, shelving-v3): New h4 subsections within #shelving, to offer more structure to the existing text. (shelving-transition): Move from Compatibility Concerns and demote to h4 within #shelving. Make title explicitly about upgrading 1.10 thru 1.13 shelves per danielsh's suggestion. (shelving-checkpointing): Make this a h4 inside #shelving per danielsh's suggestion. (viewspec-output): Move this section into #experimental. Suggested by: danielsh (portions; not including the new Experimental Features section; that's entirely my fault :-) 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=1875216&r1=1875215&r2=1875216&view=diff ============================================================================== --- subversion/site/publish/docs/release-notes/1.14.html (original) +++ subversion/site/publish/docs/release-notes/1.14.html Sun Mar 15 21:35:15 2020 @@ -135,10 +135,10 @@ and what impact these changes may have.< <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> + <a href="#shelving-transition">Upgrading 1.10–1.13 shelves to 1.14</a></td></tr> <tr> <td> - <a href="#checkpointing">Commit checkpointing (experimental)</a> + <a href="#shelving-checkpointing">Commit checkpointing (experimental)</a> </td> <td>1.12</td> <td>any</td> @@ -190,63 +190,25 @@ 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" +<div class="h3 experimental-feature" id="compatibility-shelving"> +<h3>Changes to Experimental Shelving Feature + <a class="sectionlink" href="#compatibility-shelving" 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> +#3625</a>. There is no promise of backward compatibility for features +designated "experimental."</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> +<p>Shelving in 1.14 has changed significantly since 1.10 and is incompatible +with shelves created by 1.10. See <a href="#shelving">Shelving and +Checkpointing (experimental)</a> for the major changes and differences in +commands. See its subsection, <a href="#shelving-transition">Upgrading +1.10–1.13 shelves to 1.14</a> to learn how to recover 1.10 shelves in +an existing working copy.</p> -</div> <!-- shelving-transition --> +</div> <!-- compatibility-shelving --> <!-- (This section only makes sense when there are some issues listed in it.) <div class="h3" id="compat-misc"> @@ -290,73 +252,6 @@ 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"> @@ -569,187 +464,6 @@ 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>Shelving (<a href="https://issues.apache.org/jira/browse/SVN-3625";>issue -#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 - 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> - - <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> - -<p>Because shelving is a work-in-progress, the shelving CLI is disabled by -default. Users who wish to experiment with shelving may enable one of two -different shelving CLI implementations, selectable by an environment variable -(see <a href="http://svn.apache.org/r1875037";>r1875037</a> and -<a href="http://svn.apache.org/r1875039";>r1875039</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><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> - <tr> - <td>Environment variable not set</td> - <td>No shelving CLI</td> - </tr> -</table> - -<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 - 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>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> - <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"> @@ -1066,6 +780,337 @@ The bindings can be built with SWIG 3.x </div> <!-- enhancements --> +<div class="h2" id="experimental"> +<h2>Experimental Features + <a class="sectionlink" href="#experimental" + title="Link to this section">¶</a> +</h2> + +<!-- +<p>There are no experimental features in this release at the moment.</p> +--> + +<div class="notice"> + <p>The Subversion 1.14.x release includes several "EXPERIMENTAL" features. + These are released in an early form for purposes of testing, feedback, and + to entice interested users to <a href="#enthusiastic-contributors" + >contribute</a> to their further development.</p> + + <p><span style="color: red"><b>WARNING:</b></span> Features and APIs which + are designated "EXPERIMENTAL" are considered incomplete and may change + significantly during and after the 1.14.x series. There is no promise of + backward compatibility, even from one point release to another, while they + remain experimental.</p> +</div> + +<div class="h3 experimental-feature" id="shelving"> +<h3>Shelving and Checkpointing (experimental) + <a class="sectionlink" href="#shelving" + title="Link to this section">¶</a> +</h3> + +<p>Shelving (<a href="https://issues.apache.org/jira/browse/SVN-3625";>issue +#3625</a>), first introduced in Subversion 1.10, has been developed further to +handle more kinds of changes more robustly. Two different versions of shelving +CLIs, each with different pros and cons, are available for experimentation. +Also, changes have been made under the hood to support a related feature, +Commit Checkpointing (<a href="https://issues.apache.org/jira/browse/SVN-3626"; +>issue #3626</a>).</p> + +<div class="notice"> + <p>Shelving in 1.14 is incompatible with shelves created by 1.10. See + <a href="#shelving-transition">Upgrading 1.10–1.13 shelves to 1.14</a> + to learn how to recover 1.10 shelves in a working copy.</p> +</div> + +<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>Differences in the main shelving commands since 1.10:</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 class="h4 experimental-feature" id="shelving-enabling"> +<h4>Choosing and Enabling a Shelving CLI + <a class="sectionlink" href="#shelving-enabling" + title="Link to this section">¶</a> +</h4> + +<p>Because shelving is a work-in-progress, the shelving CLI is disabled by +default. Users who wish to experiment with shelving should enable one of the +two available shelving CLI implementations by setting an environment variable +(see <a href="http://svn.apache.org/r1875037";>r1875037</a> and +<a href="http://svn.apache.org/r1875039";>r1875039</a>.)</p> + +<p>The two implementations are "Shelving-v2" as introduced in 1.11, and +"Shelving-v3" as introduced in 1.12. These 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><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> + <tr> + <td>Environment variable not set</td> + <td>No shelving CLI</td> + </tr> +</table> + +<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> + +</div> <!-- shelving-enabling --> + +<div class="h4 experimental-feature" id="shelving-v2"> +<h4>Shelving-v2 + <a class="sectionlink" href="#shelving-v2" + title="Link to this section">¶</a> +</h4> + +<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 + unshelve an older version instead of the newest—see the + <a href="#shelving-checkpointing">commit 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>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> + +</div> <!-- shelving-v2 --> + +<div class="h4 experimental-feature" id="shelving-v3"> +<h4>Shelving-v3 + <a class="sectionlink" href="#shelving-v3" + title="Link to this section">¶</a> +</h4> + +<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>This version of shelving represents a series of significant refactorings +under the hood to eventually support better shelving, commit checkpointing, +and the possibility of future client-side features for manipulating and +sharing committable changes.</p> + +</div> <!-- shelving-v3 --> + +<div class="h4 experimental-feature" id="shelving-transition"> +<h4>Upgrading 1.10–1.13 shelves to 1.14 + <a class="sectionlink" href="#shelving-transition" + title="Link to this section">¶</a> +</h4> + +<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>In Subversion 1.14, shelves are 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> + +</div> <!-- shelving-transition --> + +<div class="h4 experimental-feature" id="shelving-checkpointing"> +<h4>Commit checkpointing (experimental) + <a class="sectionlink" href="#shelving-checkpointing" + title="Link to this section">¶</a> +</h4> + +<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> + +<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> <!-- shelving-checkpointing --> + +<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>, including internal design and development +notes.</p> + +</div> <!-- shelving --> + +<div class="h3 experimental-feature" id="viewspec-output"> +<h3>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> +</h3> + +<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> + +<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> <!-- experimental --> + <div class="h2" id="issues"> <h2>Known issues in the release <a class="sectionlink" href="#issues"
