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.