Author: hartmannathan
Date: Mon Mar 3 03:47:17 2025
New Revision: 1924139
URL: http://svn.apache.org/viewvc?rev=1924139&view=rev
Log:
In staging, 1.15 release notes: Rewrite #multi-wc-format section
The Multi-WC feature has been challenging to document from a user perspective
because it pertains to "plumbing": working copy metadata format versions 31
and 32, the pristine storage types made available by each, and the resulting
working copy compatibility across Subversion releases.
Hopefully this iteration documents the feature adequately while retaining
clarity.
* 1.15.html
(#multi-wc-format): Introduce the following new subsections:
(#multi-wc-supported-formats): Document supported WC format versions and
their minimum required client version and supported Pristine types.
(#multi-wc-new-cmdline-opts): Document '--store-pristine=ARG' and
'--compatible-version=ARG' command line options, both of which affect the
WC format version chosen. Include a truth table to document the resulting
format and pristine type for all possible combinations of these options.
(#multi-wc-new-info-output): Document fields added to the output of
'svn info' in 1.15 and their meaning.
(#multi-wc-older-clients): Document error that results from invoking an
older SVN client on a Format 32 working copy.
(#multi-wc-additional-notes): Things that didn't fit elsewhere...
Modified:
subversion/site/staging/docs/release-notes/1.15.html
Modified: subversion/site/staging/docs/release-notes/1.15.html
URL:
http://svn.apache.org/viewvc/subversion/site/staging/docs/release-notes/1.15.html?rev=1924139&r1=1924138&r2=1924139&view=diff
==============================================================================
--- subversion/site/staging/docs/release-notes/1.15.html (original)
+++ subversion/site/staging/docs/release-notes/1.15.html Mon Mar 3 03:47:17
2025
@@ -516,41 +516,241 @@ href="https://svn.apache.org/repos/asf/s
title="Link to this section">¶</a>
</h3>
-<p>Subversion 1.15 introduces a new working copy format (internally called
-Format 32) to support Pristines On Demand. Subversion 1.15 or newer is
-required to operate on working copies in this new format.</p>
+<p>Subversion 1.15 introduces a new working copy format to support Pristines
+On Demand, internally called Format 32.</p>
-<p>For user convenience, Subversion 1.15 avoids the need to upgrade working
-copies unless the new features are used. This is accomplished in two ways:
+<p>In past releases, a new working copy format meant that users needed to
+upgrade any existing working copies by running <tt>svn upgrade</tt> in them.
+Once upgraded, older Subversion clients could no longer be used with these
+working copies.</p>
+
+<p>For user convenience, Subversion 1.15 introduces support for multiple
+working copy format versions (Multi-WC). This provides two benefits:</p>
+
+<ul>
+ <li>Users do not need to upgrade their 1.8 through 1.14 working copies
+ before using Subversion 1.15 with them, unless they want to use Pristines
+ On Demand.</li>
+
+ <li>Users can use a mix of Subversion 1.8 through 1.15 clients
+ interchangeably with working copies in 1.8 through 1.14 format. This
+ use case can arise when users install multiple versions of Subversion
+ clients, or use 3rd party software that incorporates older Subversion
+ releases.</li>
+</ul>
+
+<div class="h4" id="multi-wc-supported-formats">
+<h4>Supported Working Copy Formats
+ <a class="sectionlink" href="#multi-wc-supported-formats"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>Subversion 1.15 supports working copies in two format versions:</p>
+
+<table>
+ <tr>
+ <th>Working Copy Format</th>
+ <th>Introduced</th>
+ <th>Supported By</th>
+ <th>Available Pristine Types</th>
+ </tr>
+ <tr>
+ <td>Format 31</td>
+ <td>Subversion 1.8</td>
+ <td>1.8 through 1.15</td>
+ <td>Fully-Cached</td>
+ </tr>
+ <tr>
+ <td>Format 32</td>
+ <td>Subversion 1.15</td>
+ <td>1.15</td>
+ <td>Fully-Cached, Pristines On Demand</td>
+ </tr>
+</table>
+
+<p>Subversion 1.15 uses Format 31 by default, unless the user selects Format
+32 explicitly or opts in to Pristines On Demand.</p>
+
+<p>Future releases may introduce newer working copy formats while keeping
+support for existing formats.</p>
+
+</div> <!-- multi-wc-supported-formats -->
+
+<div class="h4" id="multi-wc-new-cmdline-opts">
+<h4>New Command Line Options
+ <a class="sectionlink" href="#multi-wc-new-cmdline-opts"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>Two new command line options allow users to control the working copy
+format:</p>
+
+<p><strong><tt>--store-pristine=ARG</tt></strong> can be used with
+<tt>svn checkout</tt>:</p>
+
+<ul>
+ <li><tt>--store-pristine=no</tt>: requests a working copy with Pristines
+ On Demand. This option implies working copy Format 32, supported by 1.15
+ and newer clients.</li>
+
+ <li><tt>--store-pristine=yes</tt> (default): requests a working copy with
+ traditional fully-cached Pristines. By default, the working copy will use
+ Format 31, supported by 1.8 and newer clients, unless overridden by
+ <tt>--compatible-version=1.15</tt>; see below.</li>
+</ul>
+
+<p><strong><tt>--compatible-version=ARG</tt></strong>, where <tt>ARG</tt> is
+a version of Subversion, can be used with <tt>svn checkout</tt> and
+<tt>svn upgrade</tt>:</p>
+
+<p>This requests the <em>newest</em> working copy format that is compatible
+with the specified Subversion client version.</p>
+
+<p>When choosing <tt>ARG</tt>, specify the version of the <em>oldest</em>
+Subversion client that will be used with the working copy.</p>
+
+<p><tt>ARG</tt> may be in MAJOR.MINOR format, such as <tt>1.9</tt>.
+<tt>ARG</tt> may also specify a patch version, such as <tt>1.9.5</tt> but the
+third component is ignored because Subversion does not introduce new working
+copy metadata formats in patch releases.</p>
+
+<ul>
+ <li><tt>--compatible-version=1.8</tt> through
+ <tt>--compatible-version=1.14</tt> (default): requests a working copy
+ in Format 31, supported by Subversion 1.8 and newer clients. Supports
+ traditional fully-cached Pristines only.</li>
+
+ <li><tt>--compatible-version=1.15</tt>: requests a working copy in Format
+ 32, supported by Subversion 1.15 and newer clients. Although this format
+ supports Pristines On Demand, it will use traditional fully-cached
+ Pristines by default, unless overridden by <tt>--store-pristine=no</tt>;
+ see above.</li>
+</ul>
+
+<p>The following table shows which format and pristine type is achieved by
+each combination of the <tt>--store-pristine</tt> and
+<tt>--compatible-version</tt> switches (including when omitting one or both of
+these):
</p>
+<table border="1">
+ <tr>
+ <th>--store-pristine</th>
+ <th>--compatible-version</th>
+ <th>Working Copy Format</th>
+ <th>Pristines</th>
+ </tr>
+ <tr>
+ <td>Omitted</td>
+ <td>Omitted</td>
+ <td>31</td>
+ <td>Fully cached</td>
+ </tr>
+ <tr>
+ <td>Omitted</td>
+ <td>1.8 thru 1.14</td>
+ <td>31</td>
+ <td>Fully cached</td>
+ </tr>
+ <tr>
+ <td>Omitted</td>
+ <td>1.15</td>
+ <td>32</td>
+ <td>Fully cached</td>
+ </tr>
+ <tr>
+ <td>yes</td>
+ <td>Omitted</td>
+ <td>31</td>
+ <td>Fully cached</td>
+ </tr>
+ <tr>
+ <td>yes</td>
+ <td>1.8 thru 1.14</td>
+ <td>31</td>
+ <td>Fully cached</td>
+ </tr>
+ <tr>
+ <td>yes</td>
+ <td>1.15</td>
+ <td>32</td>
+ <td>Fully cached</td>
+ </tr>
+ <tr>
+ <td>no</td>
+ <td>Omitted</td>
+ <td>32</td>
+ <td>Pristines On Demand</td>
+ </tr>
+ <tr>
+ <td>no</td>
+ <td>1.8 thru 1.14</td>
+ <td colspan="2">Not a valid combination</td>
+ </tr>
+ <tr>
+ <td>no</td>
+ <td>1.15</td>
+ <td>32</td>
+ <td>Pristines On Demand</td>
+ </tr>
+</table>
+
+</div> <!-- multi-wc-new-cmdline-opts -->
+
+<div class="h4" id="multi-wc-new-info-output">
+<h4>New <tt>svn info</tt> Output
+ <a class="sectionlink" href="#multi-wc-new-info-output"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>Users can determine the working copy format and pristine storage type with
+the <tt>svn info</tt> command (new fields shown in <b>bold</b>):</p>
+
+<pre>
+$ svn info
+Path: .
+Working Copy Root Path: /ramdrive/svn-trunk
+<span style="font-weight: bold">Working Copy Compatible With Version: 1.15
+Working Copy Format: 32
+Working Copy Store Pristine: no</span>
+URL: https://svn.apache.org/repos/asf/subversion/trunk
+Relative URL: ^/subversion/trunk
+Repository Root: https://svn.apache.org/repos/asf
+Repository UUID: 13f79535-47bb-0310-9956-ffa450edef68
+Revision: 1924024
+Node Kind: directory
+Schedule: normal
+Last Changed Author: dsahlberg
+Last Changed Rev: 1923965
+Last Changed Date: 2025-02-21 11:08:37 -0500 (Fri, 21 Feb 2025)
+</pre>
+
+<p>Explanation of the new fields:</p>
+
<ul>
- <li>Multi-WC: Subversion 1.15 introduces support for operating on multiple
- working copy formats. Currently, two formats are supported. These are:
- <ul>
- <li><b>Format 32:</b> Compatible with Subversion 1.15 and newer.
- Supports Pristines On Demand.
- </li>
-
- <li><b>Format 31:</b> Compatible with Subversion 1.8 and newer.
- Maximizes compatiblity in case older Subversion clients are used.
- </li>
- </ul>
- </li>
-
- <li>Using Format 31 by default, unless the user selects Format 32 explicitly
- or opts in to Pristines On Demand.
- </li>
+ <li><tt>Working Copy Compatible With Version</tt> shows the oldest
+ Subversion client that can be used with this working copy. In this
+ release, this field may show 1.8 or 1.15.</li>
+
+ <li><tt>Working Copy Format</tt> shows the working copy format version. In
+ this release this field may show 31 or 32.</li>
+
+ <li><tt>Working Copy Store Pristine</tt> shows <tt>no</tt> when
+ using Pristines On Demand, <tt>yes</tt> when using traditional
+ fully-cached pristines.</li>
</ul>
-<p>For example, a user who does not need Pristines On Demand may use a 1.15
-<tt>svn</tt> command line client interchangeably with a third party GUI client
-or other software package that incorporates 1.14 or older Subversion
-libraries.</p>
-
-<p>However, if using Pristines On Demand, or if Format 32 was selected
-explicitly, a 1.15 or newer client is required. Attempting to operate on such
-a working copy with an older client will result in an error, such as:</p>
+</div> <!-- multi-wc-new-info-output -->
+
+<div class="h4" id="multi-wc-older-clients">
+<h4>Older Subversion Clients
+ <a class="sectionlink" href="#multi-wc-older-clients"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>When using the newer Format 32, a Subversion 1.15 or newer client is
+required. Attempting to operate on such a working copy with an older client
+will result in an error, such as:</p>
<pre>
svn: E155021: This client is too old to work with the working copy at
@@ -559,9 +759,19 @@ You need to get a newer Subversion clien
http://subversion.apache.org/faq.html#working-copy-format-change
</pre>
-<p>Currently, Pristines On Demand is the only feature that requires a newer
-working copy format, but newer features and working copy formats to support
-them may be added in future Subversion release lines.</p>
+</div> <!-- multi-wc-older-clients -->
+
+<div class="h4" id="multi-wc-additional-notes">
+<h4>Additional Notes
+ <a class="sectionlink" href="#multi-wc-additional-notes"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>The metadata format is a property of a particular working copy. Users may
+have multiple working copies on their machine, with some in Format 31 and
+others in Format 32.</p>
+
+</div> <!-- multi-wc-additional-notes -->
</div> <!-- multi-wc-format -->
