Author: hwright
Date: Tue Jun 28 02:46:36 2011
New Revision: 1140406
URL: http://svn.apache.org/viewvc?rev=1140406&view=rev
Log:
Release docs: Move the compatibility text into its own section, and update the
text slightly (with references to the API errata).
* publish/docs/community-guide/releasing.part.html
(release-numbering): Adjust section head, remove compat text.
(release-compat): New.
Modified:
subversion/site/publish/docs/community-guide/releasing.part.html
Modified: subversion/site/publish/docs/community-guide/releasing.part.html
URL:
http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/releasing.part.html?rev=1140406&r1=1140405&r2=1140406&view=diff
==============================================================================
--- subversion/site/publish/docs/community-guide/releasing.part.html (original)
+++ subversion/site/publish/docs/community-guide/releasing.part.html Tue Jun 28
02:46:36 2011
@@ -34,103 +34,14 @@ information.</p>
<div class="h3" id="release-numbering">
-<h3>Release numbering and compatibility
+<h3>Release numbering
<a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-numbering"
title="Link to this section">¶</a>
</h3>
-<p>Subversion uses "MAJOR.MINOR.PATCH" release numbers, with the same
-guidelines as APR (see <a href="http://apr.apache.org/versioning.html";
->http://apr.apache.org/versioning.html</a>), plus a few extensions,
-described later. The general idea is:</p>
-
-<ol>
-
-<li><p>Upgrading/downgrading between different patch releases in the
- same MAJOR.MINOR line never breaks code. It may cause bugfixes
- to disappear/reappear, but API signatures and semantics remain
- the same. (Of course, the semantics may change in the trivial
- ways appropriate for bugfixes, just not in ways that would
- force adjustments in calling code.)</p>
-</li>
-
-<li><p>Upgrading to a new minor release in the same major line may
- cause new APIs to appear, but not remove any APIs. Any code
- written to the old minor number will work with any later minor
- number in that line. However, downgrading afterwards may not
- work, if new code has been written that takes advantage of the
- new APIs.</p>
-</li>
-
-<li><p>When the major number changes, all bets are off. This is the
- only opportunity for a full reset of the APIs, and while we try
- not to gratuitously remove interfaces, we will use it to clean
- house a bit.</p>
-</li>
-
-</ol>
-
-<p>Subversion extends the APR guidelines to cover client/server
-compatibility questions:</p>
-
-<ol>
-
-<li><p>A patch or minor number release of a server (or client) never
- breaks compatibility with a client (or server) in the same
- major line. However, new features offered by the release might
- be unsupported without a corresponding upgrade to the other
- side of the connection. For updating ra_svn code specifically,
- please observe these principles:</p>
-
- <ol>
-
- <li><p>Fields can be added to any tuple; old clients will simply
- ignore them. (Right now, the marshalling implementation
- does not let you put number or boolean values in the
- optional part of a tuple, but changing that will not affect
- the protocol.)</p>
-
- <p>We can use this mechanism when information is added to an
- API call.</p>
- </li>
-
- <li><p>At connection establishment time, clients and servers exchange
- a list of capability keywords.</p>
-
- <p>We can use this mechanism for more complicated changes,
- like introducing pipelining or removing information from
- API calls.</p>
- </li>
-
- <li><p>New commands can be added; trying to use an unsupported
- command will result in an error which can be checked and dealt
- with.</p>
- </li>
-
- <li><p>The protocol version number can be bumped to allow graceful
- refusal of old clients or servers, or to allow a client or
- server to detect when it has to do things the old way.</p>
-
- <p>This mechanism is a last resort, to be used when capability
- keywords would be too hard to manage.</p>
- </li>
-
- </ol>
-</li>
-
-<li><p>Working copy and repository formats are backward- and
- forward-compatible for all patch releases in the same minor
- series. They are forward-compatible for all minor releases in
- the same major series; however, a minor release is allowed to
- make a working copy or repository that doesn't work with
- previous minor releases, where "make" could mean "upgrade" as
- well as "create".</p>
-</li>
-
-</ol>
-
-<p>Subversion does not use the "even==stable, odd==unstable"
-convention; any unqualified triplet indicates a stable release:</p>
+<p>Subversion uses "MAJOR.MINOR.PATCH" release numbers. We do not use the
+"even==stable, odd==unstable" convention; any unqualified triplet indicates
+a stable release:</p>
<pre>
1.0.1 --> first stable patch release of 1.0
@@ -252,6 +163,116 @@ old name must be tossed and the next nam
</div> <!-- release-numbering -->
+<div class="h3" id="release-compat">
+<h3>Inter-release compatibility
+ <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-compat"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Subversion follows strict compatibility, with the same
+guidelines as APR (see <a href="http://apr.apache.org/versioning.html";
+>http://apr.apache.org/versioning.html</a>), plus a few extensions,
+described later. These guidelines are in place to ensure various forms of
+client/server interoperability, and make sure users have a clear upgrade
+path between MAJOR.MINOR Subversion releases.</p>
+
+<p>Compatibility can span a number of axis: everything from APIs and ABIs to
+command line output formats. We try to balance to need to modify the existing
+architecture to support new features, while still supporting current users
+to the greatest extent possible. The general idea is:</p>
+
+<ol>
+
+<li><p>Upgrading/downgrading between different patch releases in the
+ same MAJOR.MINOR line never breaks code. It may cause bugfixes
+ to disappear/reappear, but API signatures and semantics remain
+ the same. (Of course, the semantics may change in the trivial
+ ways appropriate for bugfixes, just not in ways that would
+ force adjustments in calling code.)</p>
+</li>
+
+<li><p>Upgrading to a new minor release in the same major line may
+ cause new APIs to appear, but not remove any APIs. Any code
+ written to the old minor number will work with any later minor
+ number in that line. However, downgrading afterwards may not
+ work, if new code has been written that takes advantage of the
+ new APIs.</p>
+
+ <p>(Occasionally, bugs are found which require the behavior of old APIs
+ to be modified slightly. This typically only manifests itself in
+ various corner cases and other uncommon area. These changes are
+ documented as <a
href="http://svn.apache.org/repos/asf/subversion/trunk/notes/api-errata/";>API
errata</a> for each MAJOR.MINOR release.)</p>
+</li>
+
+<li><p>When the major number changes, all bets are off. This is the
+ only opportunity for a full reset of the APIs, and while we try
+ not to gratuitously remove interfaces, we will use it to clean
+ house a bit.</p>
+</li>
+
+</ol>
+
+<p>Subversion extends the APR guidelines to cover client/server
+compatibility questions:</p>
+
+<ol>
+
+<li><p>A patch or minor number release of a server (or client) never
+ breaks compatibility with a client (or server) in the same
+ major line. However, new features offered by the release might
+ be unsupported without a corresponding upgrade to the other
+ side of the connection. For updating ra_svn code specifically,
+ please observe these principles:</p>
+
+ <ol>
+
+ <li><p>Fields can be added to any tuple; old clients will simply
+ ignore them. (Right now, the marshalling implementation
+ does not let you put number or boolean values in the
+ optional part of a tuple, but changing that will not affect
+ the protocol.)</p>
+
+ <p>We can use this mechanism when information is added to an
+ API call.</p>
+ </li>
+
+ <li><p>At connection establishment time, clients and servers exchange
+ a list of capability keywords.</p>
+
+ <p>We can use this mechanism for more complicated changes,
+ like introducing pipelining or removing information from
+ API calls.</p>
+ </li>
+
+ <li><p>New commands can be added; trying to use an unsupported
+ command will result in an error which can be checked and dealt
+ with.</p>
+ </li>
+
+ <li><p>The protocol version number can be bumped to allow graceful
+ refusal of old clients or servers, or to allow a client or
+ server to detect when it has to do things the old way.</p>
+
+ <p>This mechanism is a last resort, to be used when capability
+ keywords would be too hard to manage.</p>
+ </li>
+
+ </ol>
+</li>
+
+<li><p>Working copy and repository formats are backward- and
+ forward-compatible for all patch releases in the same minor
+ series. They are forward-compatible for all minor releases in
+ the same major series; however, a minor release is allowed to
+ make a working copy or repository that doesn't work with
+ previous minor releases, where "make" could mean "upgrade" as
+ well as "create".</p>
+</li>
+
+</ol>
+
+</div> <!-- release-compat -->
+
<div class="h3" id="deprecation">
<h3>Deprecation
<a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#deprecation"
