Subversion release process #release-process" title="Link to this section">¶
Release numbering #release-numbering" title="Link to this section">¶
Subversion uses "MAJOR.MINOR.PATCH" release numbers. We do not use the "even==stable, odd==unstable" convention; any unqualified triplet indicates a stable release:
1.0.1 --> first stable patch release of 1.0 1.1.0 --> next stable minor release of 1.x after 1.0.x 1.1.1 --> first stable patch release of 1.1.x 1.1.2 --> second stable patch release of 1.1.x 1.2.0 --> next stable minor release after that
The order of releases is semi-nonlinear — a 1.0.3 might come out after a 1.1.0. But it's only "semi"-nonlinear because eventually we declare a patch line defunct and tell people to upgrade to the next minor release, so over the long run the numbering is basically linear.
The numbers may have multiple digits. For example, 1.7.19 is the nineteenth patch release in the 1.7.x line; it was released three years after 1.7.2, and three months before 1.7.20.
Subversion releases may be qualified by text following the version number, which all represent various steps in the pre-release process. In order from least- to most-stable:
| Qualifier | Meaning | Example | Output of svn --version |
|---|---|---|---|
| Alpha | We know or expect there to be problems, but solicit testing from interested individuals. | subversion-1.7.0-alpha2 | version 1.7.0 (Alpha 2) |
| Beta | We don't expect there to be problems, but be wary just in case. | subversion-1.7.0-beta1 | version 1.7.0 (Beta 1) |
| RC (Release Candidate) | This release is a candidate to become the final proposed version. If no serious bugs are found, the -rc tag will be dropped, and the contents of this release will be declared stable. | subversion-1.7.0-rc4 | version 1.7.0 (Release Candidate 4) |
When you 'make install' subversion-1.7.0-rc1, it still installs as though it were "1.7.0", of course. The qualifiers are metadata on the release; we want each subsequent prerelease release to overwrite the previous one, and the final release to overwrite the last prerelease.
For working copy builds, there is no tarball name to worry about, but 'svn --version' still produces special output:
version 1.7.1-dev (under development)
The version number is the next version that project is working towards. The important thing is to say "under development". This indicates that the build came from a working copy, which is useful in bug reports.
Alpha and beta releases #alphas-betas" title="Link to this section">¶
When we want new features to get wide testing before we enter the formal stabilization period, we'll sometimes release alpha and beta tarballs. There is no requirement to do any beta releases even if there were "alpha1", "alpha2", etc releases; we could just jump straight to "rc1". However, there are circumstances where a beta can be useful: for example, if we're unsure of a UI decision and want to get wider user feedback before solidifying it into a formal release candidate.
Alphas and betas are only for people who want to help test, and who understand that there may be incompatible changes before the final release. The signature requirements are at the release manager's discretion. Typically, the RM will require only 1 or 2 signatures for each platform, and to tell signers that they can still sign even if their testing reveals minor failures, as long as they think the code is solid enough to make testing by others worthwhile. The RM should request that signers include a description of any errors along with their signatures, so the problems can be published when the alpha or beta release is announced.
When the alpha or beta is publicly announced, distribution packagers should be firmly warned off packaging it. See this mail from Hyrum K. Wright for a good model.
Breaking compatibility #prerelease-caveats" title="Link to this section">¶
Our compatibility rules (as detailed below) only start to apply once a final x.y.0 version has been blessed and released. Any API's, wire protocols, and on-disk formats that appeared on trunk or in an alpha/beta/rc pre-release are not subject to any compatibility promises; we may change them arbitrarily until the final release, if we find a good reason to do so. We might even remove entirely an interface or serialization format that we are not comfortable with.
This is particularly a problem for persistent data (working copies and repositories), since we might not provide an upgrade path—code paths or designated scripts for the legacy format—with the final release. (Of course, we might provide such scripts for the benefit of developers and users who test our pre-releases; but we do not obligate ourselves to do so.) Consequently, pre-releases should never be trusted with any data meant for long-term safe-keeping.
At the same time, we wish to remind the reader that the best time to point out API design bugs is before they are released and set in stone—in other words, during the initial design and pre-release stages.
Reuse of release names #name-reuse" title="Link to this section">¶
If a release or candidate release needs to be quickly re-issued due to some non-code problem (say, a packaging glitch), it's okay to reuse the same name, as long as the tarball hasn't been #tarball-signing">blessed by signing yet. However, if it has been uploaded to the standard distribution area with signatures, or if the re-issue was due to a change in code a user might run, then the old name must be tossed and the next name used.
If the old name is tossed before the would-be release tarball was published and announced to users, the tossed name is considered a non-public release, and documentation (such as CHANGES and the tag's log message) should be updated to reflect that. (See 1.8.7 for an example.) Tags and tarballs of tossed releases remain in the repository history, but they are not supported for general use (on the contrary, they are known to have release-blocker bugs).
Inter-release compatibility #release-compat" title="Link to this section">¶
Subversion follows strict compatibility, with the same guidelines as APR (see https://apr.apache.org/versioning.html), 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.
Compatibility can span a number of axes: everything from APIs and ABIs to command line output formats. We try to balance the need to modify the existing architecture to support new features, while still supporting current users to the greatest extent possible. The general idea is:
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.)
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.
(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 areas. These changes are documented as API errata for each MAJOR.MINOR release.)
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.
Subversion extends the APR guidelines to cover client/server compatibility questions:
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:
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.)
We can use this mechanism when information is added to an API call.
At connection establishment time, clients and servers exchange a list of capability keywords.
We can use this mechanism for more complicated changes, like introducing pipelining or removing information from API calls.
New commands can be added; trying to use an unsupported command will result in an error which can be checked and dealt with.
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.
This mechanism is a last resort, to be used when capability keywords would be too hard to manage.
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".
Security releases #security-releases" title="Link to this section">¶
Occasionally, security issues are reported or discovered in the Subversion which warrant special treatment when releasing. The general release process is the same, and details of how the developers treat these issues is covered elsewhere.
Custom releases #custom-releases" title="Link to this section">¶
Subversion does not distribute binary packages, but instead relies upon third-party packagers to do so. Luckily, many individuals and companies have stepped in to volunteer their efforts in this regard, and we are grateful for their efforts.
If you are a third-party packager, you may encounter instances when a bug fix or other change is important for your users, and you want to get it to them more quickly than the standard Subversion release cycle. Or you may maintain a set of patches locally which benefit your target audience. If possible, it is preferred to use the patch process and have your changes accepted and applied to trunk to be released on the normal Subversion release schedule.
However, if you feel that you need to make changes that would not be widely accepted by the Subversion developer community, or need to provide early access to unreleased features, you should follow the guidelines below. They are intended to help prevent confusion in the user community, and make both your distribution and the official Subversion releases as successful as possible.
First, make sure you follow the ASF trademark policy. You will need to differentiate your release from the standard Subversion releases to reduce any potential confusion caused by your custom release.
Second, consider creating a branch in the public Subversion repository to track your changes and to potentially allow your custom changes to be merged into mainline Subversion. (If you do not have it already, #lightweight-branches" >ask for commit access.)
Third, if your custom release is likely to generate bug reports that would not be relevant to mainline Subversion, please stay in touch with the users of the custom release so you can intercept and filter those reports. But of course, the best option would be not to be in that situation in the first place — the more your custom release diverges from mainline Subversion, the more confusion it invites. If you must make custom releases, please try to keep them as temporary and as non-divergent as possible.
Deprecation #deprecation" title="Link to this section">¶
When a new, improved version of an API is introduced, the old one remains for compatibility, at least until the next major release (2.0.0). However, we mark the old one as deprecated and point to the new one, so people know to write to the new API if at all possible. When deprecating, mention the release after which the deprecation was introduced, and point to the new API. If possible, replace the old API documentation with a diff to the new one. For example:
/**
* Similar to svn_repos_dump_fs3(), but with a @a feedback_stream instead of
* handling feedback via the @a notify_func handler
*
* @since New in 1.1.
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_repos_dump_fs2(svn_repos_t *repos,
svn_stream_t *dumpstream,
svn_stream_t *feedback_stream,
svn_revnum_t start_rev,
svn_revnum_t end_rev,
svn_boolean_t incremental,
svn_boolean_t use_deltas,
svn_cancel_func_t cancel_func,
void *cancel_baton,
apr_pool_t *pool);
When the major release number changes, the "best" new API in a
series generally replaces all the previous ones (assuming it subsumes
their functionality), and it will take the name of the original API.
Thus, marking 'svn_repos_dump_fs' as deprecated in
1.1.x doesn't mean
that 2.0.0 doesn't have 'svn_repos_dump_fs', it just means the
function's signature will be different: it will have the signature
held by svn_repos_dump_fs2
(or svn_repos_dump_fs3, or whatever) in
1.1.x. The numbered-suffix names disappear, and there is a single
(shiny, new) svn_repos_dump_fs again.
One exception to this replacement strategy is when the old function has a totally unsatisfying name anyway. Deprecation is a chance to fix that: we give the new API a totally new name, mark the old API as deprecated, point to the new API; then at the major version change, we remove the old API, but don't rename the new one to the old name, because its new name is fine.
Stabilizing and maintaining releases #release-stabilization" title="Link to this section">¶
Overview #release-stabilization-overview" title="Link to this section">¶
Minor and major number releases go through a stabilization period before release, and remain in maintenance (bugfix) mode after release. To start the release process, we create an "A.B.x" branch based on the latest trunk.
The stabilization period for a new A.B.0 release normally lasts four weeks, and allows us to make conservative bugfixes and discover showstopper issues. The stabilization period begins with a release candidate tarball with the version A.B.0-rc1. Further release candidate tarballs may be made as blocking bugs are fixed; for example, if a set of language bindings is found to be broken, it is prudent to make a new release candidate when they are fixed so that those language bindings may be tested.
Once the A.B.x branch has been created, no source code changes are ever committed to it directly; changes are backported from trunk to the A.B.x branch after being voted on, by the process described in the next sections.
At the beginning of the final week of the stabilization period, a new release candidate tarball should be made if there are any showstopper changes pending since the last one. The final week of the stabilization period is reserved for critical bugfixes; fixes for minor bugs should be deferred to the A.B.1 release. A critical bug is a non-edge-case crash, a data corruption problem, a major security hole, or something equally serious.
Under some circumstances, the stabilization period will be extended:
svn-soak-management.png
If a potentially destabilizing change must be made in order to fix a bug, the entire four-week stabilization period is restarted. A potentially destabilizing change is one which could affect many parts of Subversion in unpredictable ways, or which involves adding a substantial amount of new code. Any incompatible API change (only allowable in the first place if the new release is an A.0.0 release) should be considered a potentially destabilizing change.
If a critical bugfix is made during the final week of the stabilization period, the final week is restarted. The final A.B.0 release is always identical to the release candidate made one week before (with the exceptions discussed below).
After the A.B.0 release is out, patch releases (A.B.1, A.B.2, etc.) follow when bugfixes warrant them. Patch releases do not require a four week soak, because only conservative changes go into the line.
What changes are eligible for backport #release-stabilization-backportable-changes" title="Link to this section">¶
Certain kinds of commits can go into A.B.0 without restarting the soak period, or into a later release without affecting the testing schedule or release date:
Without voting:
Changes to the STATUS file.
Documentation fixes.
Changes that are a normal part of release bookkeeping, for example, the steps listed in Rolling a release and Creating and maintaining release branches.
Changes to dist.sh by, or approved by, the release manager.
Changes to message translations in .po files or additions of new .po files.
With voting:
Anything affecting only tools/, packages/, or bindings/.
Changes to printed output, such as error and usage messages, as long as format string "
%" codes and their args are not touched.
NOTE: The requirements on message translation changes are looser than for text messages in C code. Changing format specifiers in .po files is allowed because their validity can be checked mechanically (with the -c flag on msgfmt of GNU gettext). This is done at build time if GNU gettext is in use.
Core code changes, of course, require voting, and restart the soak or test period, since otherwise the change could be undertested.
Voting overview and the electorate #release-stabilization-voting" title="Link to this section">¶
A change to the A.B.x line must be first proposed in the A.B.x/STATUS file. Each proposal consists of a short identifying block (e.g., the revision number of a trunk or related-line commit, or perhaps an issue number), a brief description of the change, an at-most-one-line justification of why it should be in A.B.x, perhaps some notes/concerns, and finally the votes. The notes and concerns are meant to be brief summaries to help a reader get oriented. Don't use the STATUS file for actual discussion; use dev@ instead.
Here's an example, probably as complex as an entry would ever get:
* r98765 (issue #56789)
Make commit editor take a closure object for future mindreading.
Justification:
API stability, as prep for future enhancement.
Branch: 1.8.x-r98765
Notes:
There was consensus on the desirability of this feature in
the near future; see thread at http://... (Message-Id: blahblah).
Merge with --accept=mc.
Concerns:
Vetoed by jerenkrantz due to privacy concerns with the
implementation; see thread at http://... (Message-Id: blahblah)
Votes:
+1: ghudson, bliss
+0: cmpilato
-0: gstein
-1: jerenkrantz
Anyone may vote, but only full committers and partial committers for the involved areas have binding votes. When committers cast a non-binding vote (such as a partial committer voting for a change outside his nominated area), they should annotate their vote as non-binding, like this:
* r31833
svndumpfilter: Don't match prefixes to partial path components.
Fixes #desc4 of issue #1853.
Votes:
+1: danielsh, hwright
+1 (non-binding): stylesen
This distinction is made in all kinds of voting—backport voting, release voting, and the mythical votes caused by failure to reach consensus—but for different reasons. In release votes, this distinction is legally required for the release to enter ASF's legal shield, whereas in backport votes, it's closer to being an advisory distinction. After all, if someone votes -1 on a change for a sound reason, their accreditations don't matter; if their analysis is correct, the change won't be backported. Likewise, if a change fails to receive the required number of binding +1 votes but has some non-binding +1 votes, that may help it be approved.
In other words, the purpose of the backport process is to ensure destabilizing changes won't enter patch releases. Voting serves that purpose by forcing each change to undergo a certain amount of review. Since karma is not transferable, we measure "amount of review" in terms of binding votes—but as ever, anyone can give input to the process and be listened to.
Types of votes #release-stabilization-types-of-votes" title="Link to this section">¶
The voter's opinion of a change is encoded as +1, -1, +0, or -0.
Define "veto" or refer to a definition
If you cast a veto (i.e. -1), please state the reason in the concerns field, and include a url / message-id for the list discussion if any. You can go back and add the link later if the thread isn't available at the time you commit the veto.
A -0 vote means you somewhat object to a change—state your reasons in on dev@, or summarize them in a parenthetical—but won't stand in the way of consensus.
Voting +1 on a change doesn't just mean you approve of it in principle. It means you have thoroughly reviewed the change, and find it correct and as nondisruptive as possible. When it is committed to the release branch, the log message will include the names of all who voted for it, as well as the original author and the person making the commit. All of these people are considered equally answerable for bugs. Committers are trusted to know what they don't know and not cast +1 votes lightly.
If you've reviewed a patch, and like it but have some reservations, you can write "+1 (concept)" and then ask questions on the list about your concerns. You can write "+0" if you like the general idea but haven't reviewed the patch carefully. Neither of these votes counts toward the total, but they can be useful for tracking down people who are following the change and might be willing to spend more time on it.
How many votes are required #release-stabilization-how-many-votes" title="Link to this section">¶
For a non-LTS ("regular") release line, a change is approved if it receives two +1s and no vetoes. (Only binding votes count; see above.)
For an LTS release line, a change is approved if it receives three +1s and no vetoes. (Only binding votes count; see above.)
Notwithstanding the above, for any release line, a change that affects only areas that are not core code (for example, tools/, packages/, bindings/, test scripts, etc.), and that does not affect the build system, can go in with one +1 from a full committer or a partial committer for that area, at least one +0 or "concept +1" from any other committer, and no vetoes.
The goal is to get at least two pairs of eyes on the change, without demanding that every reviewer have the same amount of expertise as the area maintainer. This way one can review for general sanity, accurate comments, obvious mistakes, etc, without being forced to assert "Yes, I understand these changes in every detail and have tested them."
How to nominate changes into STATUS #release-stabilization-how-to-nominate" title="Link to this section">¶
Before proposing a change in STATUS, you should try merging it onto the branch to ensure that it doesn't produce merge conflicts. If conflicts occur, please create a new temporary branch from the release branch with your changes merged and the conflicts resolved. The branch should be named A.B.x-rYYYY, where YYYY is the first revision of your change in the STATUS file. Add a note in the STATUS file about the existence of the temporary branch in the form of a Branch: A.B.x-rYYYY or Branch: ^/subversion/branches/A.B.x-rYYYY header (use this exact form; scripts parse it). If the change involves further work, you can merge those revisions to the branch. When the entry for this change is removed from STATUS, this temporary branch should also be removed to avoid cluttering the /branches directory.
A temporary branch is also used in the rare case that a change should be made to the A.B.x branch that isn't a backport of a change from trunk.
If you nominate an entry that causes merge conflicts until another nomination is merged, note that in the nomination. Put a "Depends:" header in the entry; that will keep the hourly "detect nominations with merge conflict" buildbot job green. (The value of the "Depends:" header is not parsed.)
The tools/dist/nominate.pl script (in trunk) automates the process of adding a new nomination. The same script also has a REPL loop that helps with the process of reviewing nominations and casting votes; see tools/dist/README.backport (in trunk).
NOTE: Changes to STATUS regarding the temporary branch, including voting, are always kept on the main release branch.
Editing STATUS and annotating votes #release-stabilization-how-to-edit" title="Link to this section">¶
When adding revisions to a nomination that others have already voted on, annotate their entries with "(rX only)" to clarify what parts they have and haven't voted on, like this:
* r30643, r30653, r30785
Update bash completion script.
Votes:
+1: arfrever (r30785 only), stylesen
#obvious-fix">Obvious fixes do not require '(rX only)' to be mentioned.
If you commit someone else's vote that was communicated via other means, note that in your log message.