Google Git
Sign in
apache / forrest / trunk / . / site-author / content / xdocs / procedures / release / How_to_release.xml
blob: c69c841d221e9601087a69edf7a812ae2979b443 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
"http://forrest.apache.org/dtd/document-v20.dtd" [
<!ENTITY c '0.8'>
<!ENTITY cd 'docs_0_80'>
<!ENTITY cp 'plugins_0_80'>
<!ENTITY cs '0.80'>
<!ENTITY cb '08'>
<!ENTITY d '0.9'>
<!ENTITY dd 'docs_0_90'>
<!ENTITY dp 'plugins_0_90'>
<!ENTITY ds '0.90'>
<!ENTITY db '09'>
<!ENTITY dt '0.9-dev'>
<!ENTITY n '0.10'>
<!ENTITY nd 'docs_0_100'>
<!ENTITY np 'plugins_0_100'>
<!ENTITY ns '0.100'>
<!ENTITY nb '010'>
<!ENTITY nt '0.10-dev'>
<!ENTITY p '0.7'>
<!ENTITY pd 'docs_0_70'>
<!ENTITY ps '0.70'>
<!ENTITY pb '07'>
<!ENTITY rdate '2011-02-07'>
]>
<!-- The entities above are for the current state,
i.e. preparing for the upcoming release (using 0.8 as the example):
&c; = current release version, e.g. 0.7
&cd; = current release version docs, e.g. docs_0_70
&cp; = current release version plugin docs, e.g. plugins_0_70
&cs; = current release version site URI, e.g. 0.70 (as in site:v0.70)
&cb; = current release version brief, e.g. 07 (as in forrest_07_branch)
&d; = development version, e.g. 0.8
&dd; = development version docs, e.g. docs_0_80
&dp; = development version plugin docs, e.g. plugins_0_80
&ds; = development version site URI, e.g. 0.80 (as in site:v0.80)
&db; = development version brief, e.g. 08 (as in forrest_08_branch)
&dt; = development version with -dev, e.g. 0.8-dev
&n; = next version, e.g. 0.9
&nd; = next version docs, e.g. docs_0_90
&np; = next version plugin docs, e.g. plugins_0_90
&ns; = next version site URI, e.g. 0.90 (as in site:v0.90)
&nb; = next version brief, e.g. 09
&nt; = next version with -dev, e.g. 0.9-dev
&p; = previous version, e.g. 0.6
&pd; = previous version docs, e.g. docs_0_60
&ps; = previous version site URI, e.g. 0.60 (as in site:v0.60)
&pb; = previous version brief, e.g. 06
&rdate; = anticipated release date
-->
<document>
<header>
<title>How to release Forrest</title>
<abstract>
This document provides guidelines for the steps that a Release Manager (RM) should follow when
doing a Forrest release.
</abstract>
</header>
<body>
<section id="About">
<title>About this document</title>
<warning>
This document is constantly being developed and some steps will need to be
re-arranged. There are some fixme notes that we will review after each
release. Do not take this document at face value - always try to visualise the
effect of each step.
</warning>
<p>
This document provides guidelines for the steps that a Release Manager (RM) should follow
when doing a Forrest release. Note that it might have mistakes - we seem
to discover something new each time and some steps might need to happen
in a different order. Fine tune these notes for next time. Do some
practice runs. Read through these notes often in the lead up to the
release to imagine the effect and order of some steps.
</p>
<p>
There are some steps that other committers, and even developers, can
assist with, especially in the areas of getting ready for the release
and the final testing. Many of the steps can be done only by the Release
Manager.
</p>
<p>
The lead-up to the release is a good opportunity to build the project community
and to draw in new developers. The steps in this process try to maximise that.
</p>
<fixme author="open">
Some of the complexity in this process is due to site-author docs accompanying
the release. That is a good thing because then they have local docs.
However it complicates this process because the documentation version numbers,
xdocs layout, site.xml navigation, etc. all need to be relevant for
packing with the release. Trunk needs to stay that way during testing of RCs.
Just before the release announcement, certain things need to be updated to
create and publish the website. Then following the release, updated to be
ready for the next develoment cycle. Much of that process in unavoidable, but
some could be simplified.
</fixme>
</section>
<section id="rm">
<title>Who is a Release Manager</title>
<p>
A Release Manager is a Forrest committer who does the work of the
release process to prepare a release candidate and sign release packages, co-ordinate
testing and voting, uploading to the dist area and ensuring mirrors, and
sending the announcement.
See the <a href="http://httpd.apache.org/dev/release.html">release guidelines</a>
of the HTTP Server project, which has useful notes about the RM role.
</p>
<p>
The project developers have the role of preparing the product to release
quality, testing, fixing issues, and voting for the release candidate.
The votes of the PMC will <a href="#vote">decide</a> whether the product is fit for release.
</p>
<p>
The RM makes all the <a href="#decisionRM">calls</a> regarding the actual preparations and the
doing of the release.
</p>
<p>
The RM could do the job alone, which enables speedy process. There are
not actually many tasks where assistants can help with the release
itself (other than with the pre-release tasks and testing).
However it is a good
idea to have an assistant so as to pass on the knowledge, to help
document the process, and to perceive potential flaws. More than one
assistant would probably hinder.
</p>
<p>
The RM needs to have an incredible amount of time and energy available,
especially to prepare the first release candidate and to finalise the release.
</p>
<p>
The RM should be comfortable with using SVN and be familiar
with the distribution mirror system, and with ASF release
procedures. Also need to be a quick decision-maker and able to find and solve
issues on the spot. It would be nice if others help to solve last minute
issues, but don't expect it.
</p>
<p>
The following notes are terse. If you don't understand, then
probably not ready to be an RM.
</p>
</section>
<section id="prep">
<title>Tasks to be done by the project before the release can start</title>
<p>
There are a number of things to be done by the project before the
release will start. Don't leave these until the last minute. It is not
the Release Manager's job to fix bugs nor address blocker issues. The RM
job begins after the project is ready to do the release.
</p>
<ul>
<li>The project updates the <a href="site:bugs/filters">Roadmap</a>
to schedule the realistic Issues.
Be brutal. If these issues have not been fixed by now, then it is
quite okay to re-schedule them to delay until the next development
version. See example emails from the lead-up to previous releases.
</li>
<li>The project made good progress towards fixing the Blockers
and applying the outstanding <a href="site:bugs/filters">patches</a>.
</li>
<li>The documentation content is ready.</li>
<li>Plugins have been reviewed and deployed as necessary. Some perhaps need to
go through a release process. This should happen independently of the core release process.
</li>
<li>Supporting products (e.g. Ant, Xerces) should have been updated well before this
stage. Do not attempt such upgrades too close to the release, as it
will distract attention from other issues and possibly introduce new problems.
</li>
<li>Add some issues to the Roadmap for the important general issues that need to
happen before the release.
Some examples from last time: FOR-911, FOR-868, FOR-865, FOR-855, FOR-644.
</li>
<li>
Relevant changes are listed in the site-author/status.xml and
contributors have been attributed. Other changes are listed in the
various plugins/status.xml files.
See <a href="https://issues.apache.org/jira/browse/FOR-865">FOR-865</a>
</li>
<li>Add relevant information to the
<a href="https://issues.apache.org/jira/browse/FOR-868">upgrading notes</a>.
</li>
<li><p>
Major changes are listed in the site-author/status.xml using the
"importance" attribute. This will be used to generate the list of
top changes for the Release Notes and Announcement text.
</p>
<p>
http://localhost:8888/releaseNotes_&dt;.html
</p></li>
<li>
Committers (as many as possible) have their up-to-date PGP keys
in the KEYS file in Forrest's root directory.
Instructions about how to add keys are included in that file.
See
<a href="http://www.apache.org/dev/release-signing.html#keys-policy">instructions</a>
about how to create and manage PGP keys, and see the notes about
encouraging a strong
<a href="http://www.apache.org/dev/release-signing.html#web-of-trust">web of trust</a>.
See these tools to ensure that signatures and keys are okay:
<a href="http://people.apache.org/~henkp/checker/sig.html">pgp signature checker</a>
</li>
<li>
Be familiar with our <a href="site:guidelines/voting">voting guidelines</a> and
<a href="site:guidelines/actions">release actions</a>.
</li>
</ul>
<fixme author="open">
Decide the content of the release. Previously we just packed everything
in trunk (see the "release-dist" target) and included a built
forrest.jar file. Now there is extra stuff that should not be included.
See <a href="http://issues.apache.org/jira/browse/FOR-911">FOR-911</a>.
</fixme>
</section>
<section id="PrepProject">
<title>Preparing the project for the release</title>
<p>
In this step the Release Manager starts the process to finalise the
outstanding blocker issues.
</p>
<ol>
<li><p>
Ensure the above preconditions are met.
</p>
<p>
If not, then the project is not yet ready for release. Remember that
it is not the RM's job to do this.
</p>
<p>
If so, then send an email to get the project to decide what to do
with the remaining issues. Propose to delay some issues to a future
release, encourage people to fix others. See
<a
href="http://issues.apache.org/jira/browse/FOR-853">FOR-853</a>.
Look at
<a
href="http://www.mail-archive.com/dev@forrest.apache.org/msg02310.html" rel="nofollow">msg02310.html</a>
for an example of such a message.
</p></li>
<li><p>
Start discussion on Java-Version to use for compiling and testing
the release. If necessary, alter the build.compiler.vm value in main/build.xml and plugins/build.xml and in various other files.
Conduct a text search for the old version.
</p></li>
</ol>
</section>
<section id="PrepRM">
<title>Preparations for the Release Manager</title>
<p>
Particularly the Release Manager, but also anyone assisting, needs to be
familiar with standard procedures and Apache terminology. This is
crucial for a successful release.
</p>
<ul>
<li><p>
If you have never done a release before or need to refresh your
memory, read all about Apache releases in general at
<a href="http://www.apache.org/dev/#releases">http://www.apache.org/dev/#releases</a>
and
<a href="http://incubator.apache.org/guides/releasemanagement.html">Apache Incubator</a>.
Note that these documents change often. Make sure any assistants
have read and understood this as well.
</p></li>
<li>As discussed above, be sure that you have plenty of time and energy.
You will need to be persistent throughout the process.
</li>
<li><p>
Be familiar with the process of signing release packages and generating MD5
and PGP. Some more info is at
<a href="http://www.apache.org/dev/release-signing.html">Signing
Releases</a> and our download notes for the
<a href="http://forrest.apache.org/mirrors.cgi#verify">Verification</a>.
</p></li>
<li>Practice signing email in readiness for the announcement.</li>
<li>Investigate the release procedure notes of other ASF projects.</li>
<li>
Make sure that the network connection is reliable and efficient.
</li>
<li><p>
Install the Java-Version that has been agreed for compiling the
release. Do this well ahead of time to avoid delays, and ensure that
Forrest works for you.
</p></li>
<li>Get a printout of this document to scribble notes as you go.</li>
<li>Use a text file to prepare/record your svn merge commands.</li>
<li>Browse the dev mail list to see what happened around the previous release.
Some mails will be useful to glean words to re-use.
</li>
</ul>
</section>
<section id="PrepRelPlan">
<title>Preparing the Release Plan</title>
<p>
Prepare the Release Plan to define the corner stones of the coming
release. Deciding the dates and timing that suits everybody might be
difficult. Try to be careful about holiday periods and try to
find timing that is good to attract the most people to help.
</p>
<p>
Some items are:
</p>
<ul>
<li>Java-Version to test this release</li>
<li>The Release Manager</li>
<li>Date for end of vote on release plan</li>
<li>Date for create release candidate and start of testing period</li>
<li>Optional creation of release candidate #2 (when there are bugs)</li>
<li>Date for end of vote on the final release candidate</li>
<li>Scheduled release date</li>
</ul>
<p>
Remind people about our <a href="site:guidelines/voting">voting guidelines</a> and
<a href="site:guidelines/actions">release actions</a>.
</p>
<p>
See past release plans as examples:
<!--
<a href="http://s.apache.org/jI?action=display">0.8</a>
-->
<a href="http://s.apache.org/x5">0.9</a>
|
<a href="http://s.apache.org/jI">0.8</a>
|
<a href="http://s.apache.org/VL5">0.7</a>
</p>
<note>
There are various reasons for voting on the Release Plan, e.g.
draws attention to the release process; encourages people to get
involved; prompts people get their changes committed; ensures that the
date is suitable and
people will be around to test and then vote on the actual release. This
ensures that it is the PMC as a whole that prepares and issues the
release, rather than an individual. Such procedures give us the
protection accorded by the ASF being a corporation. See a good
discussion on the cocoon-dev list:
<a href="http://marc.theaimsgroup.com/?t=114296877800003" rel="nofollow">Re: Voting on releases?</a>
</note>
</section>
<section id="PrepCodeBase">
<title>Preparing the code base</title>
<p>
Anyone can help with this phase.
</p>
<ol>
<li><p>
Ensure that there are no license issues. The committers and PMC
would have been continually monitoring this. There are some tools to
assist with scanning for issues. See
<a href="site:tasks/legal-monitoring">further information</a>.
</p></li>
<li><p>
Ensure that the line-endings and svn:eol-style property are correct
for all files. See
<a href="site:tasks/subversion-monitoring">further
information</a>.
</p></li>
<li>
Ensure that documentation structure and content is ready.
</li>
<li>Ensure that the documentation is building properly, do 'cd site-author; forrest'. Fix any linking errors.</li>
<li>
Create a new file, etc/RELEASE-NOTES-&d;.txt, where x.y is the version currently being released.
In this file, insert the list of important changes which is obtained by doing:
http://localhost:8888/releaseNotes_&dt;.txt
<fixme author="">
move this step to later, emphasise preparing it now, e.g. in today's
there are no "important" for "docs" category.
</fixme>
<fixme author="">
Needed to hand tweak some "Link:" ... some have local URLS. Manually
removed Table of Contents.
</fixme></li>
<li>
Prepare the announcement text. Create a file admin/announcement-x.txt
(by 'svn move' the old one) and list the major new features, e.g. locationmap.
The admin directory is not included in the release package so editing can continue.
</li>
<li><p>
Ensure that each plugin that uses the locationmap has its "release
version" set to 0.8 or more.
</p>
<p>
If a plugin has a locationmap.xml file or uses "lm:" references in
its *.xmap, then it is using locationmap. See
<a href="site:buildPlugin">How to Build a Plugin</a>.
</p></li>
<li>
Ensure that plugins descriptors in both core and whiteboard are up-to-date.
</li>
<li><p>
Ensure that all relevant plugins have been deployed to plugins/&d;/
(see other notes at <a href="site:buildPlugin/release">How to Build a Plugin</a>).
</p>
<fixme author="open">
Check and integrate the documents referenced in that howto.
</fixme></li>
</ol>
</section>
<section id="PrepTrunk">
<title>Preparing your working copy of SVN trunk</title>
<fixme author="fso">
We need to discuss order from here on. My idea is to adjust docs before
we enter code freeze to save time later. But if the rc fails and release
is postponed might need to roll back changes easily and - if possible -
roll them forward later. So creating an svn branch for the rc seems to
make sense to me. Probably easiest would be to create an rc branch here
and co that. wdyt?
</fixme>
<p>
In this step you make absolutely sure that your working copy of SVN
trunk has no local modifications, or additional files that you have been
fiddling with, and especially files that might be hidden by svn:ignore
settings.
</p>
<p>
There are two ways to do this. Either do a complete new svn checkout, or
use the 'svn status --no-ignore' command on your existing working copy.
</p>
<ol>
<li><p>
In a new empty directory do <code>'svn co
https://svn.apache.org/repos/asf/forrest/trunk'</code>
</p></li>
</ol>
<p>
Alternative Approach
</p>
<ol>
<li> Do 'svn update -r HEAD' to ensure that you are up-to-date. </li>
<li> Run 'svn status --no-ignore' </li>
<li><p>
Delete any extra files you might have added/changed in your local
copy. Delete any "build" directories in plugins, etc. <strong>Extra
files must not be packed with the release.</strong> It must be a
pristine copy of the current trunk.
</p></li>
</ol>
</section>
<section id="PrepDistSvn">
<title>Preparing the "dist" SVN</title>
<p>
The SVN at
<a href="https://dist.apache.org/repos/dist/release/forrest/">https://dist.apache.org/repos/dist/release/forrest/</a>
holds some html files for the header and footer of the mirrors, and the other files that form the distribution.
This is automatically reflected by
<a href="http://www.apache.org/dev/cms.html#svnpubsub">SvnPubSub</a> on the server to
/www/www.apache.org/dist/forrest directory, which is our public distribution space.
</p>
<p>
Ensure that the KEYS file is synchronised with the copy in Forrest svn
trunk and commit the changes.
</p>
<p>
Ensure that our "dist/dev" SVN area at
<a href="https://dist.apache.org/repos/dist/dev/forrest/">https://dist.apache.org/repos/dist/dev/forrest/</a>
is ready to hold the release candidate for voting.
</p>
</section>
<section id="adjustDocs">
<title>Preparing docs for next release cycle</title>
<p>
In this phase we get the docs ready for the release. You will commit
these changes after the code-freeze, but do not publish to the website
until after the release.
</p>
<fixme author="open">
We definitely need to use automated version number strings where possible.
It is too easy to miss some, as we did with 0.8 release.
We have a set of core xml entities available.
Also see the source xml for this document, which utilises entities to
manage the version numbers between releases.
</fixme>
<ol>
<li><p>
Edit site.xml as follows:
</p>
<ol>
<li><p>
Move all version numbers one line down so that the existing:
</p>
<source>
&lt;versions tab="docs">
&lt;overview label="Overview" href="versions/index.html"/>
&lt;v&d; label="&dt;" href="site:index"/>
&lt;v&c; label="&c; (current)" href="site:v&cs;//index"/>
&lt;v&p; label="&p;" href="site:v&ps;//index"/>
&lt;versions></source>
<p>
becomes:
</p>
<source>
&lt;versions tab="docs">
&lt;overview label="Overview" href="versions/index.html"/>
&lt;v&n; label="&nt;" href="site:index"/>
&lt;v&d; label="&d; (current)" href="site:v&ds;//index"/>
&lt;v&c; label="&c;" href="site:v&cs;//index"/>
&lt;versions></source>
<p>
Similarly for <code>&lt;pluginVersions</code>
</p>
</li>
</ol></li>
<li>Similarly edit tabs.xml</li>
<li><p>
Further edit site.xml to configure the menu labels. See an example site.xml
from a past release. Basically do this ...
</p>
<ol>
<li>Add section &lt;v&ns;> with minimal content above the &lt;v&ds;> section.</li>
<li>Edit the label@ and description@ attributes for each of the three sections.
&lt;v&ns;> and &lt;v&ds;> and &lt;v&cs;></li>
<li>Remove the label@ attribute for the &lt;v&cs;> section. This prevents
it from appearing in the <a href="site:linkmap">linkmap ToC</a>.</li>
<li>Remove the whole section &lt;v&ps;> of the past docs.</li>
</ol></li>
<li>Edit version numbers in xdocs/versions/index.xml</li>
<li>Edit version numbers in xdocs/pluginDocs/index.xml</li>
<li>Edit version numbers in tools/forrestbar/</li>
<li>Edit version numbers in MOTD section of site-author/skinconf.xml</li>
<li>Edit version numbers in main/fresh-site/..../site.xml and tabs.xml</li>
<li><p>
Copy the past "Upgrading" notes from the past version.
Do: <code>svn cp site-author/content/xdocs/&pd;/upgrading_&pb;.xml site-author/content/xdocs/trash/</code>
</p></li>
<li><p>
Remove the past versions (&p;) docs directory. Do:
<code>svn rm site-author/content/xdocs/&pd;</code>
</p></li>
<li><p>
Edit site-author/conf/cli.xconf where it excludes old docs from
being generated (a trick to speed up). Adjust the version numbers.
</p></li>
<li>
Change the "fixfor" attribute to the next version for the
"project.issues-rss-url" RSS feed in the <code>site-author/forrest.properties</code> file.
Find the version number via the "Road Map" link at our Jira front page.
Verify localhost:8888/forrest-issues.html
</li>
<li><p>
Edit site-author/status.xml to
Remove the "-dev" from the current &lt;release&gt; tag, and set
the anticipated release date. Remove the "-dev" from the text intro.
</p></li>
<li>Validate status.xml (e.g. with <code>'xmllint'</code> or with <code>'forrest validate-status'</code>).</li>
<li>
<p>
Create a new directory as a stub for the next section of development docs.
Create a placeholder index page and upgrading notes. See a past release
for example. Do this ...
</p>
<source>
svn mkdir &nd;
svn copy &dd;/index.xml &nd;
svn copy &dd;/upgrading_&db;.xml &nd;/upgrading_&nb;.xml
... edit those docs to suit. Emphasise developers and encourage svn.</source>
</li>
<li>
Start the next set of development pluginDocs. Do:
<code>svn cp pluginDocs/&dp; pluginDocs/&np;</code>
</li>
<li>Remove the "dev" note from <code>&dd;/index.xml</code> and <code>&dd;/upgrading_&db;.xml</code></li>
<li><p>
Edit the Forrest home page in the "News and events" section and add
a text like:
</p>
<source>
Apache Forrest &d; was released on ## YYYY-MM-DD ##.
[### Add some important new features ###]</source></li>
<li>
Edit version numbers in the top-level quickstart <code>$FORREST_HOME/index.html</code>
</li>
<li>
Undo the exclusions of &cd; etc. in <code>site-author/conf/cli.xconf</code>
</li>
<li>Ensure that the documentation is building properly, do 'cd site-author; forrest'.
Fix any linking errors. Review changes.html to ensure section numbering.</li>
<li>Edit the site-author/content/doap.xml to add the new release date.
Note that we have copies <a href="https://issues.apache.org/jira/browse/FOR-1210">FOR-1210</a>.
</li>
<li><p>
Edit the forrest/site-author/content/xdocs/mirrors.html and adjust
all version-specific content.
In the "Verify" section near the end, add the name of the Release Manager
and the PGP key Id used to sign the release.
</p></li>
<li>
Check that the download page looks correct. Can get an idea with
<code>localhost:8888/mirrors.html</code>
</li>
<li>Search (e.g. with find and grep) to ensure that no version numbers
have been missed. Sometimes people add more hard-coded version numbers
since the last release. If you find any, then add them to the list
above (or better still, automate them).
</li>
<li>
Edit <code>site-author/conf/cli.xconf</code>
to ensure that only the old &cd; are excluded.
</li>
<li>Commit all of the above changes after the code-freeze has started
in the next section.
However do not build-and-deploy until after the release.
</li>
</ol>
<fixme author="">
Not sure what will happen with the forrestbot on our zone during this
phase. If the steps in this Release Process are correct, then such users
of live trunk should get a smooth upgrade. We will see.
</fixme>
</section>
<section id="BuildDist">
<title>Building the release candidate packages</title>
<p>
In this phase the Release Manager builds the release candidate to be
tested.
</p>
<note>
You can practice the following steps (as far as creating the branch)
without committing anything even before code-freeze. This ensures a good
release candidate.
</note>
<ol>
<li>Announce that the code-freeze has now commenced.
Use the template <a href="announce_code_freeze.txt">announce_code_freeze.txt</a>
to send email to dev list.
The meaning of "code-freeze" is defined in that template.
</li>
<li><p>
Update your SVN working copy to include any last minute changes.
Keep an eye on the svn@ mail list.
</p></li>
<li>Do any final work, such as license header checks and xml code cleanup.
</li>
<li><p>
Ensure that your Java version is the lowest specified of our
supported versions.
</p>
<note>
Set the environment variable JAVA_HOME to the path of the Java
version. Note for Windows: If you change the setting in system
properties, you need to logout and login again for the changes to
become effective.
</note></li>
<li><p>
Update the version numbers at various places:
</p>
<ol>
<li><p>
Edit main/build.xml and remove the "-dev" text around line 48:
</p>
<source>
&lt;property name="forrest.version" value="&dt;"/>
to:
&lt;property name="forrest.version" value="&d;"/>
</source></li>
<li>
Similarly in main/forrest.build.xml around line 28.
</li>
<li><p>
Edit plugins/build.xml to increase the docs version number to
the next major release. Around line 23:
</p>
<source>
&lt;property name="forrest.version" value="&d;"/>
to:
&lt;property name="forrest.version" value="&n;"/>
</source>
<note>
This is deliberately a major version up. It is assumed that new
plugins will be developed against the next version of Forrest.
Individual plugins can override this property in their own build
files.
</note></li>
</ol>
<fixme author="">
There are probably other areas which have version numbers. How can
we improve this? Possibly with XML Entities, possibly with Ant
properties.
</fixme></li>
<li><p>
Run the following quick tests from the command line of your system
to ensure that all is well:
</p>
<ul>
<li><p>
Change to the main directory and run <code>build test</code>.
The build should conclude without errors from both seed builds.
</p></li>
<li><p>
Change to the site-author directory and run 'forrest'. The docs
should build without errors.
</p></li>
</ul>
<p>
If there are any problems, focus on problems that prevent building
and invite other commiters to help you solve the problems.
</p>
<note>
It is not your job to fix bugs and code freeze should not commence
with a broken trunk.
</note>
<p>
If there are bugs with the build system that cannot be easily fixed,
then call a halt to the release process and start a discussion on
rescheduling options on the dev-list with the template
<a
href="rc_did_not_build_what_now.txt">rc_did_not_build_what_now.txt</a>
</p></li>
<li><p>
Remove the build directories from core and plugins. Do <code>svn st
--no-ignore</code> in the root directory of your release candidate
directory to be sure that all files created by the test build have
been removed and no other files have been changed. The status
command should report no changes.
</p></li>
<li>
Edit 3 files in tools/forrestbar to update the version number to match the new release:
<source>
xpi/install.rdf, line 23: &lt;em:version>&d;&lt;em:version>
xpi/install.js, line 19: var err = initInstall("ForrestBar", "forrestbar", "&d;");
xpi/chrome/content/contents.rdf, line 25: chrome:displayName="ForrestBar &d;"/>
</source></li>
<li>Build the forrestbar and replace site-author/content/xdocs/tools/forrestbar.xpi
</li>
<li>
Update the etc/RELEASE-NOTES-&d;.txt as described above.
</li>
<li>Commit all of the above changes.</li>
<li>Do 'svn up'</li>
<li><p>
Take note of the SVN revision number of your trunk by running
<code>svn info</code> from the command line in the Release
Candidate's root dir and look at the "Last Changed Rev: ######".
This will be used later for the svn log message when the branch is
created. Also it is helpful for ensuring that no new commits have
been made, i.e. people forgetting the code freeze. From here on
carefully watch the svn@ list.
</p></li>
<li><p>Cleanup your working copy to remove any extra files.</p>
<source>
cd $FORREST_HOME
find . -name build | xargs rm -rf
svn status --no-ignore</source>
</li>
<li><p>
Now we will build the release candidate packages for Windows and
Unix.
</p>
<ul>
<li>
Change to directory $FORREST_HOME/main and run <code>'build release-dist'</code>
to generate the release candidate packages.
</li>
</ul></li>
<li>
<p>Tag SVN trunk for the release candidate:</p>
<source>svn copy -r ####### -m "Create tag forrest_&db;_rc# from trunk r#######" \
https://svn.apache.org/repos/asf/forrest/trunk \
https://svn.apache.org/repos/asf/forrest/tags/forrest_&db;_rc#</source>
<p>
where 'rc#' is the release candidate number (e.g. rc1, rc2).
</p>
<p>
See
<a href="http://svn.apache.org/repos/asf/forrest/tags/">http://svn.apache.org/repos/asf/forrest/tags/</a>
for examples of past tags.
</p>
</li>
<li>Unpack and test the relevant archive in a fresh new directory.
No point getting people to test if it is broken. You need this for your own testing and vote anyway.
Be sure to set FORREST_HOME and PATH properly for this release candidate location
i.e. ensure that you are not using your trunk working copy.
</li>
<li><p id="signing">
Sign the Release Candidate packages and create the *.asc and *.md5
files.
</p>
<p>
Here is one example when using gpg and openssl from the command
line.
</p>
<source>
gpg --output apache-forrest-&d;.tar.gz.asc \
--detach-sig --armor apache-forrest-&d;.tar.gz
gpg --verify apache-forrest-&d;.tar.gz.asc \
apache-forrest-&d;.tar.gz</source>
<p>
... should say "Good signature from ..."
</p>
<source>
openssl dgst -md5 -out apache-forrest-&d;.tar.gz.md5 \
apache-forrest-&d;.tar.gz
md5sum apache-forrest-&d;.tar.gz</source>
<p>
... output should match that of the md5 file.
</p></li>
<li><p>
Create a maintenance branch in SVN. This command can be run from
anywhere because it uses full URLs.
</p>
<source>
svn copy -r ##### -m "Create the &d; release branch from r#####" \
https://svn.apache.org/repos/asf/forrest/trunk \
https://svn.apache.org/repos/asf/forrest/branches/forrest_&db;_branch
where
'#####' is the SVN revision number that the branch was created from,
which was the revision that the release candidate packages were generated from.
(Remember that you recorded this number earlier.)
</source>
<p>
See
<a href="http://svn.apache.org/repos/asf/forrest/branches/">http://svn.apache.org/repos/asf/forrest/branches/</a>
for examples of past branches, e.g. forrest_&cb;_branch
</p></li>
</ol>
</section>
<section id="vote">
<title>Testing the release candidate and voting</title>
<p>
Get Forrest developers to test the actual packges on various platforms.
</p>
<ol>
<li>
Upload the release candidate packages and signatures to the dist/dev/forrest SVN.
See <a href="#PrepDistSvn">notes</a>.
</li>
<li><p>
Use template
<a href="test_and_vote_on_rel_cand.txt">test_and_vote_on_rel_cand.txt</a>
for an email to the dev-list asking all developers to test and vote.
Don't forget to modify the template, to specify the md5sums etc.
People need to tell you the md5sum to be sure that they have tested
and voted on the correct release candidate. This is especially
important if there has been more than one release candidate.
</p></li>
<li><p>
During this testing phase, the Release Manager should:
</p>
<ul>
<li>Make sure that people are reporting that the packages unpack on different systems without problems.</li>
<li>Make sure that people have followed the actual user instructions in the Forrest
distribution at README.txt and index.html</li>
<li>Encourage people to build some difficult sites.</li>
<li>Occasionally remind people about how much time remains for testing.</li>
</ul></li>
<li id="decisionRM">
If substantial problems are revealed (not just minor glitches) then co-ordinate their
fixing by other developers. Doing the fixing of issues is not the Release Manager's job.
Deciding what constitutes a "substantial" issue is entirely the RM's call.
Remember that there is still a code freeze, so don't let people be tempted to fix other
minor stuff or add some pet new feature that they have neglected. That can easily
introduce new problems.
Of course be as accommodating as possible.
</li>
<li>If necessary start again with <a href="#BuildDist">Building the packages</a> and build another
release candidate. Remember to do 'svn update' first and to record the
new SVN revision number.</li>
<li>Tally the votes and report the result to the dev list.</li>
</ol>
<note>
It is vitally important that people review and vote against the actual
final source release candidate source packages (and not just against their SVN working copy).
</note>
</section>
<section id="FinalRel">
<title>Finalizing the release</title>
<p>
When a good release candidate has been achieved and affirmed by the
vote, we'll finalize the release.
</p>
<ol>
<li><p>
If there have been changes to the trunk since the branch was
created, then merge trunk to branch. Remember to use a proper commit message
which includes the revision number used for the merge (see the SVN Book).
</p>
<fixme author="fso">
What is the purpose of this step? It doesn't seem to be right
because trunk may already contain parts of the next version. What we
should do is do all fixing of RC-problems in the rc-branch (same as
changing docs) then, on release, merge branch back into trunk to
integrate fixes and doc-changes back into trunk. wdyt?
</fixme>
<fixme author="dc">
It should not contain new functionality because we are in a code
freeze
</fixme></li>
<li><p>
Tag SVN by doing:
</p>
<source>svn copy -m "Create tag forrest_&db;_release from release branch" \
https://svn.apache.org/repos/asf/forrest/branches/forrest_&db;_branch \
https://svn.apache.org/repos/asf/forrest/tags/forrest_&db;_release</source>
<p>
See
<a href="http://svn.apache.org/repos/asf/forrest/tags/">http://svn.apache.org/repos/asf/forrest/tags/</a>
for examples of past tags, e.g. forrest_&cb;_release
</p>
<fixme author="fso">
If we change procedure to create an rc-branch this will become a
merge changes from trunk then rename rc-branch to final release
branch. right?
</fixme></li>
<li><p>
Tag the "site" SVN by doing:
</p>
<source>svn copy -m "Create tag forrest_&db;_release_site from site" \
https://svn.apache.org/repos/asf/forrest/site \
https://svn.apache.org/repos/asf/forrest/tags/forrest_&db;_release_site</source>
</li>
<li><p>
Announce the end of the code-freeze by sending the email-template
<a
href="announce_end_of_code_freeze.txt">announce_end_of_code_freeze.txt</a>
to the dev list.
</p></li>
</ol>
</section>
<section id="prepSite">
<title>Prepare the site-author docs for next development phase</title>
<note>
Before doing anything, skip to the next section to get the upload commenced.
</note>
<p>
While waiting for the mirrors to catch up, you will copy the docs set for the
next development, then call off the code-freeze. Do this ...
</p>
<ul>
<li>Create a copy of current dev-docs in trunk for the next development phase ...
<source>
cd site-author/content/xdocs
svn rm &nd;/index.xml
svn copy &dd;/* &nd;
svn copy pluginDocs/&dp; &np;</source>
</li>
<li>Edit site.xml and add a copy of the most current versioned section (e.g. &lt;v&ds;&gt;) above it.
Increment the first decimal of the section's name to reflect the next planned release (e.g. &lt;v&ns;&gt;).
Note that some of this was already done above.
</li>
<li><p>Edit site-author/status.xml to add a new <code>
<![CDATA[<release>]]>
</code> section above it for development on the next version.
Add one placeholder action for the next "upgrading" doc.
Do the same in the release branch for a possible x.y.1
</p>
<source>
&lt;release version="&nt;" date="not yet released">
&lt;introduction>
...
&lt;/release>
&lt;release version="&d;" date="&rdate;">
&lt;action
...</source></li>
<li>Return the "dev" note to &nd;/index.xml and to &nd;/upgrading_&nb;.xml
and add some of the orginal
general points that still apply.</li>
<li>Edit site-author/conf/cli.xconf to exclude the old docs again.</li>
<li>Add new plugins directories to the "forrest/site" SVN ...
<source>
svn mkdir pluginDocs/&np;
svn mkdir plugins/&n;</source></li>
<li><p>
Edit main/build.xml, increment the version and add a -dev tag:
around line 48: &lt;property name="version" value="&nt;"/>
</p></li>
<li><p>
Edit main/forrest.build.xml and update the version: around line 28:
</p>
<source>&lt;property name="version" value="&nt;"/></source></li>
<li>Edit version numbers in plugins/build.xml</li>
<li>Edit version numbers in tools/forrestbar</li>
<li>Increment the version numbers in the head of the xml source of this
"How_to_release" document. These are xml entities which display the
various version numbers in this document.</li>
<li><p>
Update the .htaccess file to redirect /docs/dev/ to the next
version, and do other changes noted in the .htaccess file. See
site-author/content/.htaccess
</p>
<fixme author="fso">
Need to go through .htaccess and clean up.
</fixme></li>
<li>
Update the release version number and release date in xdocs/index.xml
and site-author/content/doap.xml files.
Note that we have copies <a href="https://issues.apache.org/jira/browse/FOR-1210">FOR-1210</a>.
</li>
<li>
Commit all of the above changes.
</li>
<li>Remember do not publish the website yet.</li>
<li>Send email to the dev list to remind people about the new docs set &nd;
and that we don't update &pd; set. Also remind about the new release branch
of svn. See example email from the previous release.</li>
</ul>
</section>
<section id="UploadAndAnnounce">
<title>Upload and announcement</title>
<p>
In this phase we'll upload the new Release, wait for it to be available
on most mirror sites, publish the new website, then announce the release.
</p>
<p>
The reason for waiting, is because when you send the announcement, most of
the mirrors need to be up-to-date or your audience will grumble.
See various notes below, explaining the delays.
</p>
<note>
During this phase there is a lot of waiting. While things are happening
you can be doing some of the other tasks in this Upload section and in
the <a href="#cleanup">Cleanup</a> section.
</note>
<ol>
<li>
The signatures that were provided by people who voted +1
for the release may be appended to the *.asc file.
</li>
<li><p>
Use 'svn move' to upload the release: i.e. move the *.tar.gz, the *.zip, the *.asc
and *.md5 files, and the RELEASE-NOTES-&d;.txt from dist/dev/forrest SVN to dist/release/forrest SVN.
Note that SvnPubSub will automatically publish the release.
</p>
<p>
Leave the previous distribution there as well as the new one, until after
the announcement (because mirrors.html cannot be updated until most
mirrors have received the release).
</p>
<p>
See these tools to ensure that signatures and keys are okay:
<a href="http://people.apache.org/~henkp/checker/sig.html">pgp signature checker</a>
</p>
<p>
The process is documented at
<a href="http://people.apache.org/~bodewig/mirror.html"
>http://www.apache.org/~bodewig/mirror.html</a>
and
<a
href="http://www.apache.org/dev/#releases">http://www.apache.org/dev/#releases</a>
</p>
</li>
<li>
Wait for the various mirrors to pick up the new files.
</li>
<li>
Now that the propagation is underway, return to the previous
<a href="#prepSite">section</a> to continue with documentation preparation.
</li>
<li><p>
Wait for the various mirrors to pick up the new files.
</p>
<p>
For some mirrors, this takes only a few hours. However others are
slow. How long to wait is a tradeoff, e.g. 8 hours has been the norm.
</p>
<p>
See <a href="http://www.apache.org/mirrors/">Status of mirrors</a>.
It is a very useful service and fun to watch. See the "age histogram"
near the bottom.
</p>
<p>
Take note of the time that the eu.apache.org mirror is updated, then
compare each "mirror age" to that.
</p>
<p>
When you see that a good proportion of the mirrors have received the
release, then update the website, then send the announcement.
</p></li>
<li>Ensure that docs are *not* being excluded via site-author/conf/cli.xconf
as we need to re-build the whole site.</li>
<li>Before re-building and deploying the new website, check the time.
Remember that an 'svn up' happens our on server just after the hour, then
a bit later the rsync happens and the site is live about 20 minutes past.
This site deployment will take some time, mostly because you are actually
doing a fresh installation of a local forrestbot (it does 'svn co forrest/site').
</li>
<li><p>
Re-build and publish the Forrest website as normal. Be
sure to use the new version of trunk for building the docs. Refer to
<a href="site:howToPublishDocs">Publishing Forrest Documentation</a>
for details. Beware, there is a forrestbot bug whereby with a brand new
forrest installation, the first deploy only does the added files.
So do the "build and deploy" again.
</p></li>
<li>
Use the proxy trick to do a quick review before the publishing rsync
happens (see <a href="http://apache.org/dev/project-site.html">infra notes</a>).
There might still be a chance to re-deploy.
</li>
<li>After rsync, test the new Forrest <a href="http://forrest.apache.org/">website</a>
and the redirects
<a href="http://forrest.apache.org/docs/">f.a.o/docs/</a> and
<a href="http://forrest.apache.org/docs/dev/">f.a.o/docs/dev/</a> and the
<a href="http://forrest.apache.org/mirrors.cgi">download</a> page.
</li>
<li><p>
Send <a href="announce_release.txt">announce_release.txt</a> as email to
the Forrest user and dev list and the ASF-wide announce lists.
Sign the email (e.g. PGP).
</p>
<p>
See previous announcements for examples:
<a href="http://marc.info/?l=apache-announce&amp;m=129716364828886" rel="nofollow">0.9</a>
|
<a href="http://marc.info/?l=apache-announce&amp;m=117688881228702" rel="nofollow">0.8</a>
|
<a href="http://marc.info/?l=xml-apache-announce&amp;m=111960678028211" rel="nofollow">0.7</a>
|
<a href="http://marc.info/?l=xml-apache-announce&amp;m=109784461425740" rel="nofollow">0.6</a>
|
<a href="http://marc.info/?l=xml-apache-announce&amp;m=106541447606765" rel="nofollow">0.5.1</a>
|
<a href="http://marc.info/?l=xml-apache-announce&amp;m=106352706005681" rel="nofollow">0.5</a>
|
<a href="http://marc.info/?l=jakarta-announce&amp;m=104510734501302" rel="nofollow">0.4</a>
|
<a href="http://marc.info/?l=xml-apache-announce&amp;m=104399934113331" rel="nofollow">0.3</a>
|
<a href="http://marc.info/?l=xml-apache-announce&amp;m=103746673310573" rel="nofollow">0.2</a>
</p>
</li>
<li><p>
Do the Freshmeat announcement:
<a href="http://freshmeat.net/projects/forrest/" rel="nofollow">http://freshmeat.net/projects/forrest/</a>
</p></li>
<li>
Update the release information at our
<a href="http://en.wikipedia.org/wiki/Apache_Forrest" rel="nofollow">Wikipedia</a> page.
</li>
</ol>
</section>
<section id="cleanup">
<title>Cleanup</title>
<ol>
<li>Remove the old generated docs from SVN forrest/site/&pd;
which removes them from the website.
</li>
<li><p>
One day later, remove old distribution files from the dist/release/forrest SVN.
They have already been automatically archived at
archive.apache.org/dist/forrest/
</p>
<p>
Tidy the archive area, being very careful.
</p>
<p>
See Henk's cleanup
<a href="http://people.apache.org/~henkp/tlps/">notes</a>.
</p></li>
<li>Tidy up any "site:v&c;" references. These will refer to old documentation
that will be removed at the next release. Especially status.xml file will
have such. Generalise as many as possible.
</li>
<li><p>
Do some Jira administration (need to be in the jira-administrators
group)
</p>
<ol>
<li><p>
Tweak the "release" versions via "admin" interface at our Jira.
Do this ...
</p></li>
<li><p>
Re-name the VersionIds using "Manage Versions" then "Edit
details": e.g. &dt; is renamed to &d; and &n; becomes &nt;
</p></li>
<li><p>
Mark &d; as released using "Manage Versions".
Review the Issues for the old version.
</p></li>
<li><p>
Edit the filter "FOR-roadmap-dev" to refer to the new "&n;-dev" version.
</p></li>
</ol></li>
<li>Deploy the Forrest site again.
</li>
<li>
Review Henk's
<a href="http://people.apache.org/~henkp/">pgp checks and md5 checks</a>.
</li>
</ol>
</section>
<section id="conclusion">
<title>Conclusion</title>
<p>
All done!
</p>
<p>
Or perhaps not.. if you think of anything, please refine these
instructions.
</p>
</section>
</body>
</document>