Forrest Release Process
============================
This file documents the steps a release manager should follow when making a new
Forrest release.
Preparations
------------
- 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/
- Announce the release plan to the dev list. Define when the code freeze
commences, when the vote ends etc. Use the last release plan as template:
http://www.mail-archive.com/dev@forrest.apache.org/msg02310.html
Send a reminder when the code-freeze commences.
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.
- 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. Alternatively,
run 'svn st --no-ignore' and delete any extra files that 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.
- Update the version numbers at various places.
- Edit build.xml and replace the '-dev' text with '' i.e. nothing:
around line 35:
to:
- Edit 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 29:
^^^^
around line 52:
| 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.
- 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.
e.g. J2SDK 1.4.0
- 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).
- Understand how to sign releases and generate MD5 and PGP.
http://wiki.apache.org/incubator/SigningReleases
Create the *.md5 and *.asc files.
- 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/
- 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).
- 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 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/
Upload and announcement
-----------------------
- Upload the release: the *.tar.gz, the *.zip, the *.asc and *.md5 files,
and the RELEASE-NOTES-x.y.txt
to www.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
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.
- If necessary, re-arrange stuff at the Archives site
http://archive.apache.org/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/
When you see that a good proportion of the mirrors have updated,
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
- On the server, remove the top-level files and "docs" and "howtwo"
directories using 'svn rm', then checkout the new release docs, e.g.
cd /www
svn co http://svn.apache.org/repos/asf/forrest/site/0.7 forrest.apache.org
- 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
- 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.
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
- Do the Freshmeat announcement:
http://freshmeat.net/projects/forrest/
Cleanups
--------
- Edit build.xml, increment the version and add a -dev tag:
around line 35:
- Edit main/forrest.build.xml and update the version:
around line 29:
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.
0.7-dev is renamed 0.7 and 0.8 becomes 0.8-dev
- 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
All done!
Or perhaps not.. if you think of anything, please add it here.