Forrest Release Process
=======================
This documents the steps that the 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.
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.
It is not the Release Manager's job to fix bugs nor address blocker issues.
The RM job begins when the project is ready to do the release.
Review the "FIXME" notes below.
Preparations
------------
- Start the process to finalise the outstanding blocker issues. The project
would have already prepared the Roadmap to schedule the realistic Issues.
The project would have already made good progress towards fixing the Blockers
and applying the outstanding patches. The RM should send 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 http://issues.apache.org/jira/browse/FOR-853
- Prepare the Release Plan and call for a quick vote on the dev list.
There are various reasons for voting on the Release Plan, e.g. makes people
aware that a code-freeze is about to happen; encourage them to get involved
with the release; ensure that the date is suitable and people will be around
to test and then vote on the actual release. See a good discussion
at http://marc.theaimsgroup.com/?t=114296877800003
Define when the code freeze commences, when the vote ends etc.
See email templates at end of this file.
Send a reminder when the code-freeze commences.
- Be familiar with http://www.apache.org/dev/#releases
- Ensure that as many PMC members as possible have their PGP keys in
the KEYS file.
- Ensure that there are no copyright issues. The committers and PMC would
have been continually monitoring this. There are some tools to assist
with scanning for issues, e.g.
svn:committers/relicense/src/perl/relicense.txt
svn:committers/tools/
- Ensure that the line-endings and svn:eol-style property are correct
for all files. See svn:committers/tools/
- Discuss which Java-Version to use for compiling the release.
Downloading and installing that version should be done well
ahead of time to avoid delays.
- Ensure that documentation is ready.
- Ensure that all relevant plugins have been deployed to plugins/0.8-dev/
See other notes at plugins/RELEASE_PROCESS.txt
- Check out a fresh copy from SVN to make sure you have no local
modifications, especially those that might be hidden by svn:ignore settings.
1. Create a new empty directory 'Forrest_Release'
2. svn co https://svn.apache.org/repos/asf/forrest/trunk
NOTE: This will take quite a while if you are on a dial-up connection.
See alternatives below.
Alternatively:
1. run 'svn status --no-ignore'
2. Delete any extra files you might have added/changed in your local copy.
They must not be packed with the release. It must be a pristine copy
of the current trunk.
- Send a reminder when the code-freeze commences.
================ CODE FREEZE ==============================================
Building the distribution
-------------------------
Note: You can practice the following steps (as far as creating the branch)
without committing anything. This ensures a good release candidate.
- Update your release checkout to reflect last minute changes
- Do 'build test' and 'cd site-author; forrest' to ensure that all is well.
Fix any problems, just those that prevent building.
It is not your job to fix bugs!
If there are bugs, then call a halt to the release process.
Remove the build directories from core and plugins.
Do 'svn st --no-ignore' to be sure.
- Update the version numbers at various places.
= Edit main/build.xml and replace the '-dev' text with '' i.e. nothing:
around line 45:
to:
= Edit site-author/status.xml, remove the -dev from the current tag,
and set the release date. Also add a new for development
on the next version e.g. from:
...
to:
...
= Edit main/forrest.build.xml to update the version tag to remove "-dev".
There are two occurences:
around line 32:
^^^^
around line 60:
| Forrest Site Builder |
| 0.7-dev |
^^^^
= Edit plugins/build.xml and increase the docs version number to the next major release:
around line 23:
to:
NOTE: This is deliberately a major version up. It is assumed that plugins will be
developed against the next version of Forrest. Individual plugins can override this
property in their own build files.
= Ensure that each plugin that uses the locationmap has its
"release version" set to 0.8 or more.
= Edit 4 files in tools/forrestbar to update the version number to match the new release:
- install.rdf, line 24: 0.7
- install.js, line 19: var err = initInstall("ForrestBar", "forrestbar", "0.7");
- xpi/chrome/content/contents.rdf, line 27: chrome:displayName="ForrestBar 0.7"/>
- xpi/chrome/content/forrestbarOverlay.xul, about line 40 edit the version
number as well as change the link to point to the new release's docs:
FIXME: There are probably other areas which have version numbers.
How can we improve this?
FIXME: Not sure at what stage we get rid of the old docs, e.g. 0.6
FIXME: Not sure at what stage need to edit site-author/content/xdocs/mirrors.html
(Presume that it should be done after packing release. See below.)
- Create a new file, etc/RELEASE-NOTES-x.y.txt, where x.y is the version
currently being released. It is best to copy an earlier RELEASE-NOTES file,
to keep a common layout.
In this file, provide a summary of changes, and check for general accuracy.
Scan the status.xml/changes and the Roadmap via the issues tracker,
to find the important issues.
- Set your Java version to be the lowest specified of our supported versions.
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.
- Take note of the SVN revision number of your trunk.
Do 'svn info' and look at the "Last Changed Rev: ######".
- Change to directory main and run 'build release-dist' to generate the
distributions on a UNIX machine.
- Two archives are created: apache-forrest-X.Y.tar.gz apache-forrest-X.Y.zip
- Ignore the *.zip archive.
- Repeat that on a Windows machine.
- Two archives are created: apache-forrest-X.Y.tar.gz apache-forrest-X.Y.zip
- Ignore the *.tar.gz archive.
Note: The reason for creating two separate archives is the line-endings
dilemma between Windows and UNIX. SVN ensures correct line-endings
on each operating system (as long as committers have been diligent when
adding/updating the repository).
- Do a local test of your release archive. Create a new directory,
copy the file, e.g. build/dist/apache-forrest-0.7.tar.gz
ensure that it unpacks okay, configure, and do the usual tests.
- Understand how to sign releases and generate MD5 and PGP.
Not going to try to explain, but here is some info:
http://wiki.apache.org/incubator/SigningReleases
http://forrest.apache.org/mirrors.cgi#verify
Create the *.asc and *.md5 files. Here is one example:
gpg --recv-key
gpg --output crossley-apache-forrest-0.7-RC1.tar.gz.asc \
--detach-sig --armor apache-forrest-0.7-RC1.tar.gz
gpg --verify crossley-apache-forrest-0.7.tar.gz.asc \
apache-forrest-0.7-RC1.tar.gz
... should say "Good signature from ..."
openssl dgst -md5 -out apache-forrest-0.7.tar.gz.md5 \
apache-forrest-0.7-RC1.tar.gz
md5sum apache-forrest-0.7-RC1.tar.gz
... output should match that of the md5 file.
- Create a maintenance branch in SVN with
svn copy -m "Create the x.y release branch from r#####" \
https://svn.apache.org/repos/asf/forrest/trunk \
https://svn.apache.org/repos/asf/forrest/branches/forrest_xy_branch
where 'xy' is a compact form of the version (e.g. 04, 041, 05)
and 'r#####' is the SVN revision number that the branch was created from
which was the revision that the release candidates were generated from.
See http://svn.apache.org/repos/asf/forrest/branches/
If someone has done a commit before you get to do it, then specify
the revision number with -r
- Test the actual distribution on various platforms.
- Upload the release candidates and signatures to a committer's webspace.
Use the .tar.gz from the UNIX machine and .zip from the Windows machine.
- Ask all developers to test (command-line, run, and webapp).
(See email template below.)
- Follow the actual user instructions in the Forrest distribution
at README.txt and index.html
- Use it to build some difficult sites.
- Ensure that the compressed archives will unpack correctly.
- If necessary, build the second release candidate and ask people to test again.
- When a good release candidate has been achieved, rename the files to their
final filenames and regenerate the .md5 and .asc
- Ask people to vote on the final actual release files.
- If there have been changes to the trunk since the branch was created,
then merge trunk to branch.
- If everything looks okay, and after the Vote has finished, tag SVN with
svn copy -m "Create tag forrest_xy from release branch" \
https://svn.apache.org/repos/asf/forrest/branches/forrest_xy_branch \
https://svn.apache.org/repos/asf/forrest/tags/forrest_xy
where 'xy' is a compact form of the version (e.g. 04, 041, 05).
See http://svn.apache.org/repos/asf/forrest/tags/
- Announce the end of the code-freeze to the dev list.
Upload and announcement
-----------------------
- During this phase there is a lot of waiting. While things are happening
you can be doing the Cleanups described below.
- Upload the release: the *.tar.gz, the *.zip, the *.asc and *.md5 files,
and the RELEASE-NOTES-x.y.txt
Use scp to people.apache.org at /www/www.apache.org/ dist/forrest/
Each PMC member has a server account and belongs to the forrest group.
The process is documented at http://www.apache.org/~bodewig/mirror.html
and http://www.apache.org/dev/#releases
Ensure correct file permissions: chgrp forrest *; chmod 664 *
Leave the previous dist there as well, until after the announcement.
Note: The other files there (HEAD.html README.html LICENSE.txt KEYS)
are all automatically updated from the SVN:forrest/dist/ repository.
FIXME: Add notes about the KEYS file in the "forrest-dist" SVN respository.
- If necessary, re-arrange stuff at the Archives site
http://archive.apache.org/ at dist/forrest/
You should not need to touch anything, the artifacts are automatically
copied from the main /dist/forrest/
- Wait for the various mirrors to pick up the new files.
For some mirrors, this takes only a few hours. However others are slow.
How long to wait is a tradeoff, e.g. 8 hours.
See "Status of mirrors" http://www.apache.org/mirrors/
Take note of the time that the eu.apache.org mirror is updated,
then compare each "mirror age" to that.
When you see that a good proportion of the mirrors have received the
release, then update the website, then do the announcement.
- Edit the forrest/site-author/content/xdocs/mirrors.html
- Edit the Forrest home page in the "News and events" section.
- Rebuild and publish the Forrest website as normal.
FIXME: There is a bug (FOR-300) in the forrest build which generates
to main/site/mirrors.html instead of build/site/mirrors.html
- rename the deployed plugins directory:
cd /svn/asf/forrest-site
svn up
svn mv plugins/0.8-dev plugins/0.8
svn mkdir plugins/0.9-dev
svn commit
FIXME: Not sure at what stage the docs should be copied to become docs_0_90
FIXME: Not sure at what stage the "site:v0.70" etc. replacements should happen.
- Copy the docs ready for the next development phase, e.g.
cd site-author/content/xdocs
svn copy docs_0_70 docs_0_80
- Add a new section to the top of site.xml
- Do global replace throughout docs_0_80 to replace the string
="site:v0.70 with ="site:v0.80
- Rebuild and publish the Forrest website as normal.
FIXME: Tag the forrest/site SVN. Not sure at what stage this should happen.
- 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
- Update the xml.apache.org website
Edit xml-site/src/documentation/content/xdocs/news.xml and record the
announcement, and then commit the new HTML to xml-site/targets/forrest
Note that they use forrest-0.6 to build their website.
See http://xml.apache.org/guidelines.html#website-top
- Remember that there is currently an rsync delay for all ASF websites.
http://www.apache.org/dev/project-site.html
- Send announcement email. Typically this is sent as:
To: dev@forrest.apache.org, user@forrest.apache.org, announce@apache.org,
announcements@xml.apache.org
Subject: [Announce] Apache Forrest X.Y.Z
!! Always refer them to the mirror facility
!! Never mention the URL www.apache.org/ dist/ in email or web pages.
Use the template at etc/announcement.txt
Use your spelling checker!
Sign the email (e.g. GPG) if possible.
See previous announcements:
0.2 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=103746673310573
0.3 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=104399934113331
0.4 http://marc.theaimsgroup.com/?l=jakarta-announce&m=104510734501302
0.5 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=106352706005681
0.5.1 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=106541447606765
0.6 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=109784461425740
0.7 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=111960678028211
- Do the Freshmeat announcement:
http://freshmeat.net/projects/forrest/
Cleanups
--------
- Edit main/build.xml, increment the version and add a -dev tag:
around line 45:
- Edit main/forrest.build.xml and update the version:
around line 32:
around line 52:
| Forrest Site Builder |
| 0.8-dev |
- Remove old dist files from the /www/www.apache.org/dist/forrest/ directory.
They have already been archived at archive.apache.org/dist/forrest/
- Do some Jira administration (need to be in the jira-administrators group):
- Tweak the "release" versions via "admin" interface at our Jira. Do this ...
- Re-name the VersionIds using "Manage Versions" then "Edit details":
e.g. 0.7-dev is renamed to 0.7 and 0.8 becomes 0.8-dev
- Mark 0.7 as released using "Manage Versions".
- Review the Issues for the old version and move any Incomplete ones up.
- Change the "fixfor" attribute to the next verion for the
"project.issues-rss-url" RSS feed in forrest.properties
- Cleanup this RELEASE_PROCESS.txt file to set version number examples
to be ready for the next release.
- Remove the release candidates from your public_html directory.
All done!
Or perhaps not.. if you think of anything, please refine these instructions.
------------------------------------------------------------------------------
Email templates
---------------
Here are some email templates to base the announcements. Please tweak.
------------------------------------------------------------------------------
Release Plan
The previous release has a good template. (Except that we forgot to vote.)
http://www.mail-archive.com/dev@forrest.apache.org/msg02310.html
------------------------------------------------------------------------------
Subject: [Important] code-freeze commenced
The code-freeze is now happening to allow us to pack the
release candidates and make them available for testing.
Code-freeze means *no* non-essential commits to the trunk
or to the new release branch. Other branches are free to
continue.
There should be no code enhancements or new functionality,
because that could introduce new bugs.
The main aim is to find and fix important bugs. Any minor
issues are delayed until after release (add to Jira).
Documentation corrections can happen because they will not
break anything. As long as we do test the documentation
building just prior to making the final release candidate.
However, if there are important code changes that are required
you can make a proposal to allow that commit. The PMC will
make a quick decision.
Next important milestones are:
* Create release candidate #2 if there have been changes
on Friday 2005-06-17 at 22:00 UTC [2]
[2] http://www.timeanddate.com/worldclock/meetingtime.html?day=18&month=06&year=2005&p1=48&p2=176&p3=240&p4=224&p5=213
* Actual release date is Sunday 2005-06-19 at 14:00 UTC [3]
[3] http://www.timeanddate.com/worldclock/meetingtime.html?day=20&month=06&year=2005&p1=48&p2=176&p3=240&p4=224&p5=213
Now we will go and build the releases which might take
some time. The next message will tell you where to get
the release candidates and describe how to test.
------------------------------------------------------------------------------
Subject: [Important] please test release candidate then vote
We need people to test the release candidate on your projects,
especially on different operating systems. Just send a short
reply to this thread that it works for you. See method below.
Download the release candidate and supporting files:
http://www.apache.org/~crossley/release-forrest-07/
For Windows get *.zip md5sum ################################
For UNIX get *.tar.gz md5sum ################################
Get the *.asc and *.md5 that match your chosen download.
It was packed from SVN revision ####
Java 1.4 or later is required.
If you want to verify the download, then follow:
http://forrest.apache.org/mirrors.cgi#verify
Otherwise just get on with testing.
Testing and vote period concludes Sunday 2005-06-19 14:00 UTC
Anyone can test and vote, not just PMC members.
However only the PMC votes are binding.
So we have approximately 6 days.
Here are some hints:
* Ensure that the compressed archive will unpack properly.
* Verfiy the release, especially if you are a committer.
* Follow the README.txt and index.html
* Set environment variables.
* Don't worry too much about minor bugs. We are looking
for blockers, such as it will not run. Many known issues
are recorded at our Jira, perhaps you can add more.
* Make a fresh site ...
cd my-new-dir
forrest seed
forrest run ... use the local jetty server.
forrest ... build the whole site from the command-line.
forrest war ... use your own full Jetty or Tomcat.
* Try it on the Forrest core docs ...
cd site-author
forrest run
* Forrest was already pre-built. Try building it again.
cd main
build clean
build
build test
* Try it on your own project, especially if you have
a project sitemap and use some extra plugins.
------------------------------------------------------------------------------