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/
- Discuss which Java-Version to use for compliling the release.
Downloading and installing that version should be done well
ahead of time to avoid delays.
- Announce the release plan to the dev list. Define when the code freeze
commences, when the vote ends etc. See email templates at end-of-file.
Send a reminder when the code-freeze commences.
- 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.
3. Wait for the check-out to finish
Alternatively:
1. run 'svn st --no-ignore'
2. 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.
- 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
1. cd to the 'Forrest_Release'-directory
2. svn up
3. Wait for the update to finish
- Do 'build test'. Fix any problems, just those that prevent building.
It is not your job to fix bugs.
Remove the build directories, run '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.
- 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.
On Windows you have to set the environment variable JAVA_HOME to the
path of the Java version to use.
Note: If you change the setting in the system properties, you have to logout and login
again for the changes to become effective.
- Take note of the SVN revision number of your trunk.
- 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 apache-forrest-0.7rc1.tar.gz.asc \
--detach-sig --armor apache-forrest-0.7rc1.tar.gz
gpg --verify crossley-apache-forrest-0.7.tar.gz.asc \
apache-forrest-0.7rc1.tar.gz
... should say "Good signature from ..."
openssl dgst -md5 -out apache-forrest-0.7.tar.gz.md5 \
apache-forrest-0.7rc1.tar.gz
md5sum apache-forrest-0.7rc1.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.
- Ask people to vote on the final release candidate.
- 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/
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
FIXME: that needs to change now. It will be a once off.
- 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 refine these instructions.
------------------------------------------------------------------------------
Email templates
---------------
Here are some email templates to base the announcements. Please tweak.
------------------------------------------------------------------------------
Release plan
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.
------------------------------------------------------------------------------