Author: hartmannathan
Date: Tue Feb 25 05:02:05 2025
New Revision: 1924032
URL: http://svn.apache.org/viewvc?rev=1924032&view=rev
Log:
In staging, 1.15 release notes: Overhaul the #compatibility subsection
Over many years and release lines, the "Compatibility Concerns" section has
accumulated a substantial amount of information. The 1.15 release introduces
features that require even more text to explain properly. To do so without
adjusting the presentation would make this section rather unwieldy in my
opinion. This overhaul hopefully improves clarity and guides readers toward
the information they seek while making it easier to skip text that does not
apply to them.
* 1.15.html
(#compatibility): To improve clarity, split into subsections.
(#compatibility-client-server,
#compatibility-repository,
#compatibility-working-copy,
#compatibility-api-abi): The aforementioned new subsections.
(#new-feature-compatibility-table): Fill in the table.
(#wc-upgrade): Try to make the remaining text as clear as possible by only
disussing when and how to upgrade an older working copy. Remove all text
that isn't directly related to this, such as discussions of working copy
formats 31 and 32, using working copies interchangeably with 1.8 through
1.14 clients, etc. These items will be addressed in other sections in a
followup.
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=1924032&r1=1924031&r2=1924032&view=diff
==============================================================================
--- subversion/site/staging/docs/release-notes/1.15.html (original)
+++ subversion/site/staging/docs/release-notes/1.15.html Tue Feb 25 05:02:05
2025
@@ -74,31 +74,79 @@ file.</p>
title="Link to this section">¶</a>
</h2>
-<p>Older clients and servers interoperate transparently with 1.15
+<div class="h3" id="compatibility-client-server">
+<h3>Client/Server Compatibility
+ <a class="sectionlink" href="#compatibility-client-server"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Subversion 1.15 clients and servers interoperate transparently with older
servers and clients. However, some of the new 1.15 features may not be
available unless both client and server are the latest version. There are
-also cases where a new feature will work but will run less efficiently if
-the client is new and the server old.</p>
+also cases where a new feature will work but will run less efficiently if the
+client is new and the server old.</p>
+
+</div> <!-- compatibility-client-server -->
+
+<div class="h3" id="compatibility-repository">
+<h3>Repository Compatibility
+ <a class="sectionlink" href="#compatibility-repository"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Subversion 1.15 servers can read and write to repositories created by
+earlier versions.</p>
<p>There is <strong>no need</strong> to <a
href="http://svnbook.red-bean.com/en/1.8/svn.reposadmin.maint.html#svn.reposadmin.maint.migrate.svnadmin";
->dump and reload</a> your repositories.
-Subversion 1.15 servers can read and write to repositories created by
-earlier versions. To upgrade an existing server installation, just install the
-newest libraries and binaries on top of the older ones.</p>
-
-<p>Subversion 1.15 maintains API/ABI compatibility with earlier
-releases, by only adding new functions, never removing old ones. A
-program written to any previous 1.x API can both compile
-and run using 1.15 libraries. However, a program written for 1.15
-cannot necessarily compile or run against older libraries.</p>
-
-<p>There may be limited cases where the behavior of old APIs has been
-slightly modified from previous releases. These are cases where edge cases
-of the functionality have been deemed buggy, and therefore improved or removed.
-Please consult the
-<a
href="https://svn.apache.org/repos/asf/subversion/trunk/notes/api-errata/1.15/";
->API errata</a> for more detailed information on what these APIs are
-and what impact these changes may have.</p>
+>dump and reload</a> your repositories.
+
+</div> <!-- compatibility-repository -->
+
+<div class="h3" id="compatibility-working-copy">
+<h3>Working Copy Compatibility
+ <a class="sectionlink" href="#compatibility-working-copy"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Subversion 1.15 can upgrade 1.0 through 1.7 working copies in place. See
+<a href="#wc-upgrade">Upgrading the Working Copy</a> below.</p>
+
+<p>Subversion 1.15 is fully compatible with 1.8 through 1.14 working copies
+(without upgrading) and can be used interchangeably with Subversion 1.8
+through 1.14 clients on these working copies.</p>
+
+<p>Additionally, Subversion 1.15 introduces a new working copy format to
+support the Pristines On Demand feature added in this release. Working copies
+in this newer format require a Subversion 1.15 or newer client and cannot be
+used with Subversion 1.14 or older clients.</p>
+
+<p>To maximize compatibility, by default both <tt>svn checkout</tt> and
+<tt>svn upgrade</tt> produce working copies which can be used interchangeably
+with Subversion 1.8 through 1.14 clients, except when the user requests
+Pristines On Demand or requests the newer working copy format.</p>
+
+</div> <!-- compatibility-working-copy -->
+
+<div class="h3" id="compatibility-api-abi">
+<h3>API/ABI compatibility
+ <a class="sectionlink" href="#compatibility-api-abi"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Subversion 1.15 maintains API/ABI compatibility with earlier releases, by
+only adding new functions, never removing old ones. A program written to any
+previous 1.x API can both compile and run using 1.15 libraries. However, a
+program written for 1.15 cannot necessarily compile or run against older
+libraries.</p>
+
+<p>There may be limited cases where the behavior of old APIs has been slightly
+modified from previous releases. These are instances where edge cases of the
+functionality have been deemed buggy, and therefore improved or removed.
+Please consult the <a
href="https://svn.apache.org/repos/asf/subversion/trunk/notes/api-errata/1.15/";
+>API errata</a> for more detailed information on what these APIs are and what
+impact these changes may have.</p>
+
+</div> <!-- compatibility-api-abi -->
<div class="h3" id="new-feature-compatibility-table">
<h3>New Feature Compatibility Table
@@ -111,7 +159,22 @@ and what impact these changes may have.<
<th>Minimum Client<sup>1</sup></th>
<th>Minimum Server</th>
<th>Minimum Repository</th>
- <th>Notes</th></tr>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>Pristines On Demand</td>
+ <td>1.15</td>
+ <td class='todo'>TODO</td>
+ <td class='todo'>TODO</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>Streamy Checkouts</td>
+ <td>1.15</td>
+ <td class='todo'>TODO</td>
+ <td class='todo'>TODO</td>
+ <td></td>
+ </tr>
</table>
</div> <!-- new-feature-compatibility-table -->
@@ -122,49 +185,31 @@ and what impact these changes may have.<
title="Link to this section">¶</a>
</h3>
-<p>Subversion 1.15 supports the working copy formats used by Subversion 1.0 and
-newer, as follows:</p>
+<p>Subversion 1.15 is fully compatible with 1.8 through 1.14 working copies.
+These do not need to be upgraded.</p>
+
+<p>Subversion 1.15 can upgrade most 1.0 through 1.7 working copies in place
+but cannot otherwise operate on them until upgraded.</p>
-<ul>
+<p>In some cases, it may be more convenient to check out a new working copy,
+rather than to upgrade an older one.</p>
-<li>Before using Subversion 1.15 with an existing <b>Subversion 1.7 or
older</b>
-working copy, users will be required to run the <tt>svn upgrade</tt> command
-to upgrade working copy metadata to the new format. This command may take a
-while in some cases, and for some users, it may be more practical to simply
-checkout a new working copy.</li>
-
-<li>Subversion 1.15 can read and write existing <b>Subversion 1.8 through
1.14</b>
-working copies in-place, <em>without upgrading them</em>. Subversion 1.8
-through 1.15 can be used interchangeably on such working copies. (Internally,
-these are termed "format 31" working copies.)</li>
-
-<li>Additionally, Subversion 1.15 adds a new working copy format that
-cannot be read by Subversion 1.14 and older. (Internally, these are termed
-"format 32" working copies.)</li>
-
-</ul>
-
-<p>By default, both <tt>svn checkout</tt> and <tt>svn upgrade</tt> will
-produce working copies supported by Subversion 1.8 through 1.15
(format-31).</p>
-
-<p>To instruct Subversion to use a particular working copy format, pass the new
-<tt>--compatible-version=1.15</tt> command-line option to these commands. This
-will choose the newest format that is compatible with the specified version of
-Subversion. If you use multiple Subversion clients, pass the version number of
-the <em>oldest</em> client that will operate on the working copy.</p>
-
-<p class='todo'>Document what's new in format 32</p>
-
-<p><strong>Note:</strong> Subversion 1.15 cannot upgrade working copies that
-a 1.6 client would have refused to operate upon before an <tt>svn cleanup</tt>
-was run (with a 1.6 client). In other words, before upgrading to 1.8 or newer,
-a 1.6
-or older client must be used to run <tt>svn cleanup</tt> on all 1.6 or older
-working copies that require cleanup. Likewise, Subversion 1.15 cannot upgrade
-corrupt working copies. Unfixable problems can arise from missing or corrupt
-meta-data inside <tt>.svn</tt> directories. Such damage to the working copy
-is permanent, and cannot be fixed even if <tt>svn cleanup</tt> is run prior
-to the upgrade.</p>
+<p>To upgrade a working copy, run the <tt>svn upgrade</tt> command in it.
+This command may take some time to complete.</p>
+
+<p><strong>Caveats:</strong></p>
+
+<p><strong>1.6 and older working copies:</strong> In the event that a 1.6 or
+older working copy requires <tt>svn cleanup</tt>, the cleanup must be
+performed <em>by a 1.6 or older Subversion client</em>. Subversion 1.15
+cannot upgrade these in place until the cleanup is run with the older
+client.</p>
+
+<p><strong>Corrupt working copies:</strong> Subversion 1.15 cannot upgrade
+<em>corrupt</em> working copies. Unfixable problems can arise from missing or
+corrupt meta-data inside <tt>.svn</tt> directories. Such damage to the
+working copy is permanent, and cannot be fixed even if <tt>svn cleanup</tt> is
+run prior to the upgrade.</p>
<p>If your working copy does not upgrade cleanly, please check out a new one.
</p>
