Apache Tomcat Release Process
Introduction
This is written primarily for Apache Tomcat release managers although it may also be of interest to anyone looking to validate and/or replicate the release process. This page uses Tomcat 9 as an example but the same process applies to later versions as well.
Pre-requisites
- A git client installed and on your path
- Apache Ant installed and on your path (see BUILDING.txt in the root of the code repository for version requirements)
- The latest release of the minimum Java version that the Tomcat version runs on installed and on your path
- Operating system
- Windows just works
- Linux also requires wine (standard package manager version should be fine)
- MacOS also requires wine (see below)
- GnuPG installed
- A public key that is part of the Apache web of trust
- A reasonable internet connection (you will need to upload ~100MB)
The above can be accomplished on a Windows 10 Virtual Machine from Microsoft's Edge Development resources. Download + unpack the archive for your VM software and launch the VM. Login, open a PowerShell.exe window as Administrator, and installed Chocolatey:
PS C:\Users\IEUser> Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
Once Chocolatey is installed, you can install all the above prerequisites at once:
PS C:\Users\ISUser> choco install git svn adoptopenjdk8 ant gnupg sed xsltproc
This command will run for a while, and ask you repeatedly if it's okay to run "chocolateyInstall.ps1", which you will have to do to proceed. Once the above command has completed, you have all the software prerequisites installed and on your PATH. Well, once you quick PowerShell and launch a new CMD.EXE or PowerShell window, of course
wine on MacOS
This is for 11.x.x (Big Sur)
You will need to install homebrew if you haven't already.
Then install wine-crossover from https://github.com/Gcenx/homebrew-wine
Configure a 32-bit wine environment using:
WINEARCH=win32 WINEPREFIX=~/.wine32 winecfg
Then before you start the release ensure the following environment variables are set:
export WINEARCH=win32
export WINEPREFIX=~/.wine32
Preliminary checks
- Check that the version numbers have been incremented after the previous release, as expected. (e.g. https://github.com/apache/tomcat/commit/cec14f9c33af9da271c9681bf6b343c61b6d055a)
- Check that the changelog file mentions your login name as release manager for this release (e.g. "Tomcat 9.0.94 (markt)").
- Check whether the
KEYS
file differs fromhttps://dist.apache.org/repos/dist/release/tomcat/tomcat-9/KEYS
one. The latter one will be replaced after you do a release. Check that theKEYS
file contains your public key. - Check that the full build still works (ant release, preferably). Check that Buildbot builds (https://tomcat.apache.org/ci.html#Buildbot) are green.
Create the tag
The aim is to create a copy of the current trunk but without the "-dev" appended to the end of the version number.
- Perform an git clone and switch to the correct branch
git clone https://github.com/apache/tomcat /c/releases/asf-tomcat
orgit clone -b 9.0.x git clone https://github.com/apache/tomcat /c/releases/asf-tomcat
cd /c/releases/asf-tomcat
git checkout 9.0.x
git pull
Edit "build.properties.default" and change the lines after "# ----- Reproducible builds -----" to a new value.
- Note that the value of
ant.tstamp.now
property is in seconds (unlike the value returned bySystem.currentTimeMillis()
method which is milliseconds, see bug 65527 for how this happened for Tomcat 8.5.70).
The value can be printed in a Bash shell with the following command:date +%s
To print seconds since epoch, and date and time in human-readable format in UTC time zone:date -u '+%s %Y-%m-%d %H:%M:%S %Z'
- Note that the value of
Edit "build.properties.default" and change the line version.suffix=-dev to version.suffix=
- This can be done with
sed -i.bak "s/^version.suffix=.*/version.suffix=/" build.properties.default
- This can be done with
- Edit "webapps/docs/changelog.xml" and remove rtext="in development" from the latest version
- Remember that notepad.exe will remove UTF-8 Byte-Order Marks (BOMs). Use write.exe or Notepad++ instead.
- Commit these changes
git commit -a -m "Tag 9.0.94"
git tag 9.0.94
git push origin 9.0.94
- Check the diff mailed to the dev list
- Reset to the 9.0.x branch (
git reset HEAD~ && git checkout build.properties.default && git checkout webapps/docs/changelog.xml
)
I found it simplest to keep this clone for tagging to ensure no other edits found their way into the tag.
Build the release
- Set JVM to Java 7 (Tomcat 8.5.x) or 8 (Tomcat 9.0, 10.0) or 11 (Tomcat 10.1)
- mkdir /c/releases/TOMCAT_9_0_94
- git archive 9.0.94 | tar -x -C /c/releases/TOMCAT_9_0_94/
I'm using Git Bash for the above. Adjust as necessary for you choice of tools.
- Add a build.properties file with the following configuration (adjust paths for your environment)
execute.validate=true execute.test.bio=true execute.test.nio=true execute.test.apr=true test.haltonfailure=true gpg.exec=C:/Program Files (x86)/GNU/GnuPG/gpg2.exe #gpg.exec=/usr/bin/gpg base.path=C:/temp/libs #base.path=~/tomcat-libs # Enable the following if the DigiCert ONE magic is all set up, including ~/.digicertone/pkcs11properties.cfg #do.codesigning=true
ant release
Notes:
- GPG should be configured to use your Apache code signing key by default
- I always ensured
c:/temp/libs
was empty so that the build had to download all the dependencies - This does not include the signing of the Windows installer, which must be done using https://one.digicert.com/ and https://infra.apache.org/digicert-use.html which is automated during the build process once the Tomcat PMC key is accessible by using jsign. (Working? Try setting
do.codesigning=true
in build.properties). - The logs for the Windows signing are in ~/.signingmanager/logs on Linux
- If you get an error signing the installer/uninstaller "Cannot load keystore ~/.digicertone/pkcs11properties.cfg" then you probably don't have your environment variables set properly.
Upload the release
Upload the contents of TOMCAT_9_0_XX/output/release
to https://dist.apache.org/repos/dist/dev/tomcat/tomcat-9/
svn checkout https://dist.apache.org/repos/dist/dev/tomcat/tomcat-9
- cp -r TOMCAT_9_0_XX/output/release/* tomcat-9
- cd tomcat-9 && svn add v* && svn commit -m "Upload vX.Y.Z for voting"
Generate the Maven artifacts
See https://github.com/apache/tomcat/blob/9.0.x/res/maven/README.txt steps 1 to 3 for the release (not step 4 until the vote passes !)
Call a vote
- E.g. http://markmail.org/message/gvmbwocspnwb2dfe
- Increment the version number ready for the next tag (e.g. http://svn.apache.org/viewvc?view=revision&revision=1500094)
If the vote passes
- Send a recap "[VOTE][RESULT]" email to the vote thread on the dev list with the vote counts.
svn mv https://dist.apache.org/repos/dist/dev/tomcat/tomcat-9/v9.0.XX https://dist.apache.org/repos/dist/release/tomcat/tomcat-9/v9.0.XX
svn checkout --depth immediates https://dist.apache.org/repos/dist/release/tomcat/tomcat-9/
and update the
KEYS
file there to be the same as the one used for release. (The download page has links pointing to this file).- Release the Maven artifacts (https://github.com/apache/tomcat/blob/9.0.x/res/maven/README.txt step 4)
- Wait for the mirrors to sync (up to 24 hours depending on what percentage of the mirrors you want to sync) (Check status at https://apache.org/mirrors/)
- Update the website (e.g. http://svn.apache.org/viewvc?view=revision&revision=1500109)
Note: the index and oldnews pages are sorted by date. Thus the new announcement pops up to the top of the page. - Update the docs (see http://svn.apache.org/repos/asf/tomcat/site/trunk/README.txt)
- Announce the release (e.g. http://markmail.org/message/xyantb3ozzmucdjt) to users@t.a.o, cc dev@t.a.o, announce@t.a.o, announce@a.o
- Update the release date in the changelog to the date the files were copied to the the release area in yyyy-mm-dd format.
E.g. "released 2013-05-03" (for stable versions), "beta, 2007-02-08" (for betas). - Add the version number in Bugzilla (https://bz.apache.org/bugzilla/ → Administration → Products / versions)
- Drop the artifacts for the previous release from https://dist.apache.org/repos/dist/release/tomcat/tomcat-9/
- Add release data (version and date) to reporter.apache.org - https://reporter.apache.org/addrelease.html?tomcat
If the vote does not pass
- Update the release date in the changelog to "not released"
- Drop the artifacts from https://dist.apache.org/repos/dist/dev/tomcat/tomcat-9/
- Drop the maven artifacts from the staged maven repository