Author: gstein
Date: Tue Jun 28 01:57:24 2011
New Revision: 1140396
URL: http://svn.apache.org/viewvc?rev=1140396&view=rev
Log:
Apply <tt> wrappers around filenames, and switch from <code> to <tt> for
non-code items.
* site/publish/docs/community-guide/releasing.part.html:
(...): lots of fixed-width font changes. fix a duplicate "steps"
reference in some of the recent prose. adjust the output of
'svn --version' to match latest updates.
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=1140396&r1=1140395&r2=1140396&view=diff
==============================================================================
--- subversion/site/publish/docs/community-guide/releasing.part.html (original)
+++ subversion/site/publish/docs/community-guide/releasing.part.html Tue Jun 28
01:57:24 2011
@@ -16,14 +16,14 @@ order of specificity:</p>
addresses the question of "How do I manage a release?"</li>
<li>How to constructing a set of release tarballs. This section discusses
the steps required to go from source code in the repository to a set of
- distributable <code>.tar.gz</code> or <code>.zip</code> files with the
+ distributable <tt>.tar.gz</tt> or <tt>.zip</tt> files with the
desired content.</li>
</ul>
<p>Subversion release managers use a set of steps codified in a Python script
-named <code><a
href="http://svn.apache.org/repos/asf/subversion/trunk/tools/dist/release.py";>release.py</a></code>.
-This script can be used to perform most of the automated steps in the steps
-in the release process. Run it with the <code>-h</code> option to get more
+named <a
href="http://svn.apache.org/repos/asf/subversion/trunk/tools/dist/release.py";><tt>release.py</tt></a>.
+This script can be used to perform most of the automated steps
+in the release process. Run it with the <tt>-h</tt> option to get more
information.</p>
<div class="h2" id="release-numbering">
@@ -168,21 +168,23 @@ prereleases leading to 1.3.7 might look
<p>(See <a href="<!--#echo var="GUIDE_RELEASING_PAGE" -->#alphas-betas">this
section</a> for more information
about when and how we do alpha and beta releases.)</p>
-<p>When you 'make install' subversion-1.3.7-rc1, it still installs as
+<p>When you '<tt>make install</tt>' subversion-1.3.7-rc1,
+it still installs as
though it were "1.3.7", 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.</p>
<p>For working copy builds, there is no tarball name to worry about,
-but 'svn --version' still produces special output:</p>
+but '<tt>svn --version</tt>' still produces special output:</p>
<pre>
- version 1.3.8 (dev build)
+ version 1.3.8-dev (under development)
</pre>
<p>The version number is the next version that project is working
-towards. The important thing is to say "dev build". This indicates
+towards. The important thing is to say "<tt>under development</tt>".
+This indicates
that the build came from a working copy, which is useful in bug
reports.</p>
@@ -243,12 +245,14 @@ API documentation with a diff to the new
<p>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
+Thus, marking '<code>svn_repos_dump_fs</code>' as deprecated in
+1.1.x doesn't mean
+that 2.0.0 doesn't have '<code>svn_repos_dump_fs</code>', 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
+held by <code>svn_repos_dump_fs2</code>
+(or <code>svn_repos_dump_fs3</code>, or whatever) in
1.1.x. The numbered-suffix names disappear, and there is a single
-(shiny, new) svn_repos_dump_fs again.</p>
+(shiny, new) <code>svn_repos_dump_fs</code> again.</p>
<p>One exception to this replacement strategy is when the old function
has a totally unsatisfying name anyway. Deprecation is a chance to
@@ -334,21 +338,24 @@ schedule or release date:</p>
<ul>
<li><p>Without voting:</p>
<ul>
- <li><p>Changes to the STATUS file.</p></li>
+ <li><p>Changes to the <tt>STATUS</tt> file.</p></li>
<li><p>Documentation fixes.</p></li>
<li><p>Changes that are a normal part of release bookkeeping, for
- example, the steps listed in notes/releases.txt.</p></li>
- <li><p>Changes to dist.sh by, or approved by, the release manager.</p></li>
- <li><p>Changes to message translations in .po files or additions of
- new .po files.</p></li>
+ example, the steps listed in <tt>notes/releases.txt</tt>.</p></li>
+ <li><p>Changes to <tt>dist.sh</tt> by, or approved by, the
+ release manager.</p></li>
+ <li><p>Changes to message translations in <tt>.po</tt> files or
+ additions of
+ new <tt>.po</tt> files.</p></li>
</ul>
</li>
<li><p>With voting:</p>
<ul>
- <li><p>Anything affecting only tools/, packages/, or bindings/.</p></li>
+ <li><p>Anything affecting only <tt>tools/</tt>, <tt>packages/</tt>,
+ or <tt>bindings/</tt>.</p></li>
<li><p>Changes to printed output, such as error and usage messages, as
- long as format string "%" codes and their args are not
+ long as format string "<code>%</code>" codes and their args are not
touched.</p></li>
</ul>
</li>
@@ -356,7 +363,7 @@ schedule or release date:</p>
</ul>
<p>NOTE: The requirements on message translation changes are looser
-than for text messages in C code. Changing format specifiers in .po
+than for text messages in C code. Changing format specifiers in <tt>.po</tt>
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.</p>
@@ -367,13 +374,13 @@ or test period, since otherwise the chan
<p>The voting system works like this:</p>
<p>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
+<tt>A.B.x/STATUS</tt> 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; please
-don't use the STATUS file for actual discussion, use dev@ instead.</p>
+don't use the <tt>STATUS</tt> file for actual discussion, use dev@ instead.</p>
<p>Here's an example, probably as complex as an entry would ever
get:</p>
@@ -397,7 +404,7 @@ get:</p>
committers for the involved areas), and no vetoes, to go into
A.B.x. If partial committers would like to vote for a different area,
which does not fall within their privilege, it must be made clear in
-the STATUS file that their vote is 'non-binding' as follows:</p>
+the <tt>STATUS</tt> file that their vote is 'non-binding' as follows:</p>
<pre>
* r31833
@@ -443,7 +450,7 @@ toward the total, but they can be useful
are following the change and might be willing to spend more time on
it.</p>
-<p>When votes are listed in the STATUS file, they are placed into a
+<p>When votes are listed in the <tt>STATUS</tt> file, they are placed into a
section for a given release. Some developers may want to vote the
change into a <b>later</b> release, if (for example) they believe it
requires further review or testing. Simply add a comment along with
@@ -480,19 +487,20 @@ one can review for general sanity, accur
mistakes, etc, without being forced to assert "Yes, I understand these
changes in every detail and have tested them."</p>
-<p>Before proposing a change in STATUS, you should try merging it onto
+<p>Before proposing a change in <tt>STATUS</tt>, 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
+branch should be named <tt>A.B.x-rYYYY</tt>, where YYYY is the first revision
+of your change in the <tt>STATUS</tt> file. Add a note in the
+<tt>STATUS</tt> file
about the existence of the temporary branch. 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
+entry for this change is removed from <tt>STATUS</tt>, this temporary branch
should also be removed to avoid cluttering the /branches
directory.</p>
-<p>NOTE: Changes to STATUS regarding the temporary branch, including
+<p>NOTE: Changes to <tt>STATUS</tt> regarding the temporary branch, including
voting, are always kept on the main release branch.</p>
<div class="h3" id="alphas-betas">
@@ -747,14 +755,14 @@ detailed?</i></p>
title="Link to this section">¶</a>
</h3>
-<p>Run <code>svn log -rHEAD:BRANCH_POINT
-http://svn.apache.org/repos/asf/subversion/branches/A.B.x</code>,where
-BRANCH_POINT is the revnum where the previous major/minor release was
+<p>Run <tt>svn log -rHEAD:BRANCH_POINT
+http://svn.apache.org/repos/asf/subversion/branches/A.B.x</tt>, where
+<var>BRANCH_POINT</var> is the revnum where the previous major/minor release
was
branched off of the trunk. This should give you every change ever
made to the A.B.x line, including backports made to the A.B.x branch.
You then need to <em>remove</em> logs of changes that have already
been released in micro releases of the previous major/minor branch.
-Run <code>svn log -q --stop-on-copy</code> on the previous release
+Run <tt>svn log -q --stop-on-copy</tt> on the previous release
branch, and then write a script to parse the revnums and remove them
from your primary log output. (Karl and Ben used to use emacs macros
to do that, but suggest that we write a more general script.)</p>
@@ -822,8 +830,8 @@ software with <tt>--prefix=/opt/svnrm</t
run <tt>dist.sh</tt> to be sure that <tt>/opt/svnrm/bin</tt> is at the
front of your <tt>PATH</tt>.</p>
-<p>You can do all of the forgoing with the <code>build-env</code> subcommand
-of release.py.</p>
+<p>You can do all of the forgoing with the <tt>build-env</tt> subcommand
+of <tt>release.py</tt>.</p>
</div> <!-- before-release -->
@@ -855,9 +863,9 @@ PATH="/opt/svnrm/bin:$PATH" ./dist.sh -v
<p>Watch <tt>dist.sh</tt>'s output to make sure everything goes
smoothly; when it's done, you'll have zipfiles in the cwd.</p>
-<pre>
-Test one or both of the tarballs:
+<p>Test one or both of the tarballs:</p>
+<pre>
a) tar zxvf subversion-X.Y.Z.tar.gz; cd subversion-X.Y.Z
b) ./configure
@@ -946,12 +954,12 @@ Test one or both of the tarballs:
</pre>
<p><b>Subversion Operations</b></p>
-<p>Create the tag with the svn_version.h that reflects the final
+<p>Create the tag with the <tt>svn_version.h</tt> that reflects the final
release. You do this by updating your working copy to the release
revision, 1234 in the example below. Run svnversion to verify that
you do not have a mixed working copy or modified working copy, i.e.
svnversion outputs only the release revision (not 1234:1235 or 1234M).
-Then place the svn_version.h.dist file in place in the working copy
+Then place the <tt>svn_version.h.dist</tt> file in place in the working copy
and copy from the working copy to the tag URL. For example:</p>
<pre>
@@ -964,8 +972,8 @@ and copy from the working copy to the ta
<p>Note: Please always make a tag, even for release candidates.</p>
-<p>Bump the svn_version.h for the original branch. If you just did
-1.0.2 then svn_version.h should have the proper values for 1.0.3 and
+<p>Bump the <tt>svn_version.h</tt> for the original branch. If you just did
+1.0.2 then <tt>svn_version.h</tt> should have the proper values for 1.0.3 and
so on.</p>
</div> <!-- rolling-release -->
@@ -1048,24 +1056,26 @@ freshmeat crew before it goes public.</p
<p><b>Update the website</b></p>
<ol>
- <li>Edit the ^/subversion/site/publish/source-code.html page to note
+ <li>Edit the <tt>^/subversion/site/publish/source-code.html</tt> page to note
the latest release.</li>
- <li>Add new News item to ^/subversion/site/publish/news.html
+ <li>Add new News item to <tt>^/subversion/site/publish/news.html</tt>
announcing the release. Add the same item to the News list on
- ^/subversion/site/publish/index.html, also removing the oldest News item
+ <tt>^/subversion/site/publish/index.html</tt>, also removing the
+ oldest News item
from that page.</li>
<li>List the new release on the
- ^/subversion/site/publish/docs/release-notes/release-history.html
+ <tt>^/subversion/site/publish/docs/release-notes/release-history.html</tt>
page.</li>
<li>Ensure that the community release support levels on
- ^/subversion/site/publish/docs/release-notes/index.html
+ <tt>^/subversion/site/publish/docs/release-notes/index.html</tt>
are still up-to-date, tweaking as necessary.</li>
<li>Commit the modifications.</li>
<li>Create or update the versioned documentation snapshots in
-^/site/publish/docs/api/X.Y and ^/site/publish/docs/javahl/X.Y, and
-ensure that the "latest" symlinks which are siblings of those
-directories always point to the directories of the latest release
-series. Commit those changes, too.</li>
+ <tt>^/site/publish/docs/api/X.Y</tt> and
+ <tt>^/site/publish/docs/javahl/X.Y</tt>, and
+ ensure that the "latest" symlinks which are siblings of those
+ directories always point to the directories of the latest release
+ series. Commit those changes, too.</li>
</ol>
