Author: hwright
Date: Tue Jun 28 21:23:01 2011
New Revision: 1140852
URL: http://svn.apache.org/viewvc?rev=1140852&view=rev
Log:
Release docs: move a couple more sections into the master section on creating
a release.
* publish/docs/community-guide/releasing.part.html
(before-release, rolling-release): Move into release-creating, and make h3.
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=1140852&r1=1140851&r2=1140852&view=diff
==============================================================================
--- subversion/site/publish/docs/community-guide/releasing.part.html (original)
+++ subversion/site/publish/docs/community-guide/releasing.part.html Tue Jun 28
21:23:01 2011
@@ -822,178 +822,11 @@ [email protected].</p>
</div> <!-- releasing-release -->
-</div> <!-- release-creating -->
-
-
-<div class="h2" id="release-branches">
-<h2>Creating and maintaining release branches
- <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-branches"
- title="Link to this section">¶</a>
-</h2>
-
-<p>A new release branch is created for each new major and minor
-release. So, for example, a new release branch is created when
-preparing to release version 2.0.0, or version 1.3.0. However, when
-preparing to release 1.3.1 (a patch-version increment), the release
-branch created at the time of 1.3.0 is used.</p>
-
-<p>If you are preparing for a patch release, then there is no release
-branch to create. You just pick up where you left off in the current
-minor version series release branch.</p>
-
-<p>The time at which a new release branch needs to be created is fuzzy
-at best. Generally, we have a soft schedule of releasing a new minor
-version every 6 months. So, approximately 4 months after the previous
-minor release is a good time to start proposing a branch. But remember
-that this is flexible, depending on what features are being
-developed.</p>
-
-<p>Once people agree that a new release branch should be made, the
-Release Manager creates it with the following procedure (substitute
-A.B with the version you're preparing, eg. 1.3, or 2.0):</p>
-
-<ul>
-<li><p>Create the new release branch with a server-side copy:</p>
- <pre>
- svn cp https://svn.apache.org/repos/asf/subversion/trunk \
- https://svn.apache.org/repos/asf/subversion/branches/A.B.x \
- -m "Create A.B.x release branch."
- </pre></li>
-
-<li><p>Edit <tt>subversion/include/svn_version.h</tt> on trunk and
- increment the version numbers there. Do not commit these changes
- yet.</p>
- <p>The version number on trunk always reflects the major/minor
- version that will immediately follow the one for which you just
- created a branch (eg. 2.1.0 for the 2.0.x branch, and 1.4.0 for
- the 1.3.x branch).</p></li>
-
-<li><p>Edit <tt>CHANGES</tt> on trunk to introduce a new section for the
- upcoming release. The section starts with:</p>
- <pre>
- Version A.B.0 (released ?? ????? 20XX, from /branches/A.B.x)
- http://svn.apache.org/repos/asf/subversion/tags/A.B.0
- </pre>
- <p>Leave the release date blank for now. It will remain this way
- until rolling time.</p></li>
-
-<li><p>Commit both these changes with the following log message:</p>
- <pre>
- Increment the trunk version number, and introduce a new CHANGES
- section for the upcoming A.B.0 release.
-
- * subversion/include/svn_version.h: Increment version number.
-
- * CHANGES: New section for A.B.0.
- </pre></li>
-</ul>
-
-</div> <!-- release-branches -->
-
-
-<div class="h2" id="porting-changes">
-<h2>Porting changes to release branches
- <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#porting-changes"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Once a release branch has been created, no development <i>ever</i>
-takes place there. The only changes permitted are ones made to
-various bookkeeping files such as <tt>STATUS</tt>, and changes merged
-in from trunk. In rare cases, a feature branch may be created from the
-A.B.X branch to address issues specific to the release branch (for example,
-to fix a bug that does not affect trunk).</p>
-
-<p>The protocol used to accept or refuse the merging of changes from
-trunk is of interest to all Subversion developers, and as such is
-documented in <a href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-stabilization">the
-release stabilization section</a>.</p>
-
-</div> <!-- porting-changes -->
-
-
-<div class="h2" id="the-changes-file">
-<h2>Managing the CHANGES file
- <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#the-changes-file"
- title="Link to this section">¶</a>
-</h2>
-
-<p>The <tt>CHANGES</tt> file is the project changelog file. Before a
-release, it must be brought up to date to list all changes since the
-last release.</p>
-
-<p>For patch-releases, this is fairly easy: you just need to walk
-through the commit logs for the branch since the last "golden"
-revision, and note all interesting merges. For minor and major
-releases, this is more complex: you need to traverse the commit log on
-<em>trunk</em> since the last release branch was forked, and make note
-of all changes there. It's the same procedure, but a lot longer, and
-somewhat more complex as it involves filtering out changesets that
-have already been backported to previous release branches and released
-from there.</p>
-
-<p>Remember that <tt>CHANGES</tt> should <em>always</em> be edited on
-trunk and then merged over to the release branch(es) when necessary.
-It is very important that all changes of all releases be documented in
-the <tt>CHANGES</tt> file on trunk, both for future reference and so that
-future release branches contain the sum of all previous change
-logs.</p>
-
-<p>Keep the bullet point for each change concise, preferably no more
-than one line long. Sometimes that can be a challenge, but it really
-adds to the overall readability of the document. Think to yourself:
-<i>If it takes more than one line to describe, maybe I'm getting too
-detailed?</i></p>
-
-<div class="h3" id="writing-initial-changes">
-<h3>Writing the initial content for a branch
- <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#writing-initial-changes"
- title="Link to this section">¶</a>
-</h3>
-
-<p>Run <tt>svn log --stop-on-copy ^/subversion/branches/A.B.x</tt>.
-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 <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>
-
-<p>Read that log from oldest to newest, summarizing points as you go.
-The trick is to know what level of detail to write at: you don't want
-to mention every tiny little commit, but you don't want to be too
-general either. Set your filter-level by reading through a few pages
-of the <tt>CHANGES</tt> file before starting on the new section, just to
-keep things consistent.</p>
-
-</div> <!-- writing-initial-changes -->
-
-<div class="h3" id="adding-changes">
-<h3>Adding content for patch release
- <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#adding-changes"
- title="Link to this section">¶</a>
-</h3>
-
-<p>As part of <a href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-stabilization">release
-stabilization</a>, <tt>CHANGES</tt> should be updated as bug fixes are
-ported to the release branch. Generally, if you merge a revision or group
-of revisions (i.e., an item in <tt>STATUS</tt>) to the release branch, you
-should also add an item to <tt>CHANGES</tt> on trunk, following the same
-guidelines outlined above. This list will then be merged to the release
-branch when a patch release is made.</p>
-
-</div> <!-- adding-changes -->
-
-</div> <!-- the-changes-file -->
-
-
-<div class="h2" id="before-release">
-<h2>Preparing to roll a release
+<div class="h3" id="before-release">
+<h3>Preparing to roll a release
<a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#before-release"
title="Link to this section">¶</a>
-</h2>
+</h3>
<p>So, a release branch has stabilized, and you are gearing up to roll
the release. Before you can actually roll the archives, you need to
@@ -1030,11 +863,11 @@ of <tt>release.py</tt>.</p>
</div> <!-- before-release -->
-<div class="h2" id="rolling-release">
-<h2>Rolling a release
+<div class="h3" id="rolling-release">
+<h3>Rolling a release
<a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#rolling-release"
title="Link to this section">¶</a>
-</h2>
+</h3>
<p>Before rolling, first make sure that the latest version of the
<tt>CHANGES</tt> file from trunk is merged into the release branch, and that
@@ -1169,6 +1002,172 @@ so on.</p>
</div> <!-- rolling-release -->
+</div> <!-- release-creating -->
+
+
+<div class="h2" id="release-branches">
+<h2>Creating and maintaining release branches
+ <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-branches"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>A new release branch is created for each new major and minor
+release. So, for example, a new release branch is created when
+preparing to release version 2.0.0, or version 1.3.0. However, when
+preparing to release 1.3.1 (a patch-version increment), the release
+branch created at the time of 1.3.0 is used.</p>
+
+<p>If you are preparing for a patch release, then there is no release
+branch to create. You just pick up where you left off in the current
+minor version series release branch.</p>
+
+<p>The time at which a new release branch needs to be created is fuzzy
+at best. Generally, we have a soft schedule of releasing a new minor
+version every 6 months. So, approximately 4 months after the previous
+minor release is a good time to start proposing a branch. But remember
+that this is flexible, depending on what features are being
+developed.</p>
+
+<p>Once people agree that a new release branch should be made, the
+Release Manager creates it with the following procedure (substitute
+A.B with the version you're preparing, eg. 1.3, or 2.0):</p>
+
+<ul>
+<li><p>Create the new release branch with a server-side copy:</p>
+ <pre>
+ svn cp https://svn.apache.org/repos/asf/subversion/trunk \
+ https://svn.apache.org/repos/asf/subversion/branches/A.B.x \
+ -m "Create A.B.x release branch."
+ </pre></li>
+
+<li><p>Edit <tt>subversion/include/svn_version.h</tt> on trunk and
+ increment the version numbers there. Do not commit these changes
+ yet.</p>
+ <p>The version number on trunk always reflects the major/minor
+ version that will immediately follow the one for which you just
+ created a branch (eg. 2.1.0 for the 2.0.x branch, and 1.4.0 for
+ the 1.3.x branch).</p></li>
+
+<li><p>Edit <tt>CHANGES</tt> on trunk to introduce a new section for the
+ upcoming release. The section starts with:</p>
+ <pre>
+ Version A.B.0 (released ?? ????? 20XX, from /branches/A.B.x)
+ http://svn.apache.org/repos/asf/subversion/tags/A.B.0
+ </pre>
+ <p>Leave the release date blank for now. It will remain this way
+ until rolling time.</p></li>
+
+<li><p>Commit both these changes with the following log message:</p>
+ <pre>
+ Increment the trunk version number, and introduce a new CHANGES
+ section for the upcoming A.B.0 release.
+
+ * subversion/include/svn_version.h: Increment version number.
+
+ * CHANGES: New section for A.B.0.
+ </pre></li>
+</ul>
+
+</div> <!-- release-branches -->
+
+
+<div class="h2" id="porting-changes">
+<h2>Porting changes to release branches
+ <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#porting-changes"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>Once a release branch has been created, no development <i>ever</i>
+takes place there. The only changes permitted are ones made to
+various bookkeeping files such as <tt>STATUS</tt>, and changes merged
+in from trunk. In rare cases, a feature branch may be created from the
+A.B.X branch to address issues specific to the release branch (for example,
+to fix a bug that does not affect trunk).</p>
+
+<p>The protocol used to accept or refuse the merging of changes from
+trunk is of interest to all Subversion developers, and as such is
+documented in <a href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-stabilization">the
+release stabilization section</a>.</p>
+
+</div> <!-- porting-changes -->
+
+
+<div class="h2" id="the-changes-file">
+<h2>Managing the CHANGES file
+ <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#the-changes-file"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>The <tt>CHANGES</tt> file is the project changelog file. Before a
+release, it must be brought up to date to list all changes since the
+last release.</p>
+
+<p>For patch-releases, this is fairly easy: you just need to walk
+through the commit logs for the branch since the last "golden"
+revision, and note all interesting merges. For minor and major
+releases, this is more complex: you need to traverse the commit log on
+<em>trunk</em> since the last release branch was forked, and make note
+of all changes there. It's the same procedure, but a lot longer, and
+somewhat more complex as it involves filtering out changesets that
+have already been backported to previous release branches and released
+from there.</p>
+
+<p>Remember that <tt>CHANGES</tt> should <em>always</em> be edited on
+trunk and then merged over to the release branch(es) when necessary.
+It is very important that all changes of all releases be documented in
+the <tt>CHANGES</tt> file on trunk, both for future reference and so that
+future release branches contain the sum of all previous change
+logs.</p>
+
+<p>Keep the bullet point for each change concise, preferably no more
+than one line long. Sometimes that can be a challenge, but it really
+adds to the overall readability of the document. Think to yourself:
+<i>If it takes more than one line to describe, maybe I'm getting too
+detailed?</i></p>
+
+<div class="h3" id="writing-initial-changes">
+<h3>Writing the initial content for a branch
+ <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#writing-initial-changes"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Run <tt>svn log --stop-on-copy ^/subversion/branches/A.B.x</tt>.
+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 <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>
+
+<p>Read that log from oldest to newest, summarizing points as you go.
+The trick is to know what level of detail to write at: you don't want
+to mention every tiny little commit, but you don't want to be too
+general either. Set your filter-level by reading through a few pages
+of the <tt>CHANGES</tt> file before starting on the new section, just to
+keep things consistent.</p>
+
+</div> <!-- writing-initial-changes -->
+
+<div class="h3" id="adding-changes">
+<h3>Adding content for patch release
+ <a class="sectionlink" href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#adding-changes"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>As part of <a href="<!--#echo var="GUIDE_RELEASING_PAGE"
-->#release-stabilization">release
+stabilization</a>, <tt>CHANGES</tt> should be updated as bug fixes are
+ported to the release branch. Generally, if you merge a revision or group
+of revisions (i.e., an item in <tt>STATUS</tt>) to the release branch, you
+should also add an item to <tt>CHANGES</tt> on trunk, following the same
+guidelines outlined above. This list will then be merged to the release
+branch when a patch release is made.</p>
+
+</div> <!-- adding-changes -->
+
+</div> <!-- the-changes-file -->
+
<div class="h2" id="releasing-not">
<h2>How <em>not</em> to make a Subversion release
