Create a GeoServer Release

This is a guide to making a GeoServer release available to the general project. The GeoServer project very much believes in the mantra of 'release early, release often'. Our users should have our latest developments as soon as possible, as their feedback and involvement is significant part of our success. Due to the distributed nature of the project you will need a lot of permissions on different systems to put a release out. If you are attempting a release you should be in close contact with a project admin who can help guide you through the process and give you the appropriate permissions.

To create a GeoServer release, just follow this simple 19 step process! Check Geotools dependencies Checkout Geotools from Subversion Build Geotools Checkout GeoServer from Subversion Build and Unit Test Hand Test CITE Test Tag and Branch Update GeoServer Version Create a README Build Release Artifacts Export Documentation from Confluence Create Windows Installer Test Runnable Artifacts Upload to SourceForge Update the Website Move Open JIRA Issues Upload to Codehaus Maven Repository Announce the Release

Step 0: Prerequisites

The following are necessary to perform the release:

• A working GeoServer build environment, with Maven
• Commit rights on subversion repository (https://svn.codehaus.org/geoserver)
• Admin rights on GeoServer SourceForge project (https://geoserver.sourceforge.net)
• A stable and relatively fast internet connection

Step 1: Check Geotools dependencies

GeoServer needs to be released against a stable version of Geotools. This means that either:

1. There is a stable Geotools version already that satisfies GeoServer needs
2. GeoServer needs a stable release of Geotools to be created (because it needs some bug fixes
   committed only on the gt2 stable branch, but still unreleased)

Most often, a new release of Geotools will be required before performing a release of GeoServer.  That said, when releasing an experimental (non-stable) release of GeoServer, it is acceptable to release against a Geotools snapshot.

Run CITE tests to verify that this version is compliant.  If more bugfixes are needed, commit them to the stable branch, and declare a code freeze and the need for a new stable release on the Geotools developer mailing list.  Keep the freeze until all CITE tests do pass and a new stable release that Geoserver can use is finished.

If you are building on a machine with no graphical user interface, some tests will fail. You can get around this by appending -Djava.awt.headless=true to your maven commands.

Step 2: Checkout Geotools from Subversion

The Geotools repository is at http://svn.geotools.org/.  Check out the appropriate tag/snapshot for your release.

Step 3: Build Geotools

Build Geotools using maven:

mvn clean install -Dall

If in charge of the Geotools release, tag it so you know what revision GeoServer was released against. Ideally you would just do a full Geotools release as well.

Step 4: Checkout GeoServer from Subversion

Ensure you have a current source tree by checking out from scratch or performing an update.

GeoServer subversion repository https://svn.codehaus.org/geoserver

Step 5: Build and Unit Test

Make sure the main pom.xml refers to the correct Geotools version, and that the GeoServer version is the one you're releasing.

<properties>
	<gs.version>1.6.4</gs.version> # Replace version number with current GeoServer version
	<gt.version>2.4.3</gt.version>  # Replace version number with current Geotools version
</properties>

Do a full build using mvn clean install, which will run unit tests along the way. If a test fails, it must be fixed before releasing.

Step 6: Hand Test

This simply means try out GeoServer and observe the results on a few tests. To do this:

1. From the web module:

   [./geoserver/web]% mvn -DconfigId=release -DconfigDirectory=../../configuration clean install

2. From the same module, start the embedded jetty container:

   [./geoserver/web]% mvn jetty:run

3. Issue a few WMS and WFS requests via the Map Preview in the Demo area of the admin console to verify that GeoServer is functioning.
4. A quick look through the configuration is also a good idea.

If any error is found, it must be fixed and the build and test process restarted.

Step 7: CITE Test

Step-by-step guide to running CITE tests

The CITE tests are very important, but will take a very time to run all the way, so we recommend working on some documentation or the README file (see below) while they run. The tests are available at http://cite.opengeospatial.org/. To run them you will need a public instance of GeoServer outside of a firewall.

Step 8: Tag and Branch

Commit any remaining changes to your local checkout.

1. Create a tag:

   svn copy https://svn.codehaus.org/geoserver/trunk https://svn.codehaus.org/geoserver/tags/<version>

2. If the release is a "major release"( one in which the secondary version number has changed ), create a branch:

   svn copy https://svn.codehaus.org/geoserver/trunk https://svn.codehaus.org/geoserver/branches/<major>-<secondary>-x

   Where major is the major and secondary version numbers. Example: 1.4.x

Step 9: Update GeoServer Version

Update all files which contain a reference to the old version number.

A handy UNIX command for doing so is defined and explained below.

This action is very powerful, and can make unwanted changes, so make sure that the syntax is correct! When in doubt, check svn diff, and use svn revert if an error was made.

[./geoserver]% find . -type f ! -path '*/.svn/*' -exec sed -i 's/1\.6\.0-SNAPSHOT/1\.6\.3/g' {\} \;

{\} \;

On Windows you can do the same using, for example, the free "Simple Search and Replace" utility from RJL software.

The set of files to be updated include:

• all pom.xml files in all directories
• ./geoserver/release/geoserver.nsi
• ./geoserver/web/src/main/java/ApplicationResources*
• ./geoserver/community/community-schemas/web-c/src/main/java/ApplicationResources*

Also, since you will be working from a tag, make sure to update the version number on the branch.  For example, if creating the 1.6.4 release, make sure that the branch is renamed to 1.6.5-beta.

Step 10: Create a README

The README file (located in the ./geoserver/release directory) must be updated for every release. Be sure to copy the updated README.txt to the branch which you are tagging, and back to trunk.

When writing the README follow the following guidelines:

1. It should be few paragraphs, highlighting the new features of the release
2. It should contain credits to anyone who contributed during the development cycle, contributions include testing, reporting bugs, submitting patches, etc.
3. It should contain a reference to the JIRA issue log
4. It should contain a reference to the version of Geotools the release is built against

Example README:

GeoServer 1.4.0
---------------

Major features / improvements of this release include:

- new SLD editor
- WMS PutStyles / GetStyles support
- WFS filter parsing bug fix

Special thanks to the following people for their contributions:

- Joe Schmo: WFS filter parsing patch

The issue log for this release can be found here:

http://jira.codehaus.org/secure/IssueNavigator.jspa?reset=true&pid=10311&fixfor=11555

Based on Geotools 2.2.0 (tag = 2.2.0).

The search/replace command from Step 9 will probably have edited this README.txt file, so make sure to undo any unwanted changes!

Step 11: Build Release Artifacts

1. Make sure your configuration/release directory does not contain any extra file or local modifications. To make extra sure, just wipe it out and svn up it back.
2. From the root of the release directory

   [./geoserver/release]% mvn clean install

   You should hopefully see something like this

   ...
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESSFUL
   [INFO] ------------------------------------------------------------------------
   ...

3. From the root of the source tree, run these two commands:

   [./geoserver]% mvn -DconfigId=release -DconfigDirectory=../../configuration clean install

   [./geoserver]% mvn -DconfigId=release -DconfigDirectory=../../configuration javadoc:javadoc assembly:attached -Dmaven.test.skip=true

You should hopefully see the following:

...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...

A ./geoserver/target/release directory will have been created which contains the following artifacts:

geoserver-(version)-arcsde-plugin.zip
geoserver-(version)-bin.zip
geoserver-(version)-doc.zip
geoserver-(version)-db2-plugin.zip
geoserver-(version)-gml-plugin.zip
geoserver-(version)-gwc-plugin.zip
geoserver-(version)-javadoc.zip
geoserver-(version)-mysql-plugin.zip
geoserver-(version)-oracle-plugin.zip
geoserver-(version)-pyramid-plugin.zip
geoserver-(version)-src.zip
geoserver-(version)-vpf-plugin.zip
geoserver-(version)-war.zip
geoserver-(version)-wfsv-plugin.zip

Step 12: Export Documentation from Confluence

You should now head over to the Confluence Wiki (geoserver.org) and export the docs:

1. Navigate to Browse Space -> Advanced -> Export Space.
2. Select HTML format, and uncheck Include comments.
3. Scroll down to the bottom of the page and hit the Export button.
4. Save the generated zip file and rename to geoserver-(version)-doc.zip.  Overwrite the existing doc file that was created in the previous step.

Step 13: Create Windows Installer

This step must be performed on a Windows OS.

In order to create the windows installer, you will need to download and install the Nullsoft Scriptable Install System (NSIS).

1. make a new temporary directory (refered to as temp).
2. uncompress target/release/geoserver-(version)-bin.zip to the temporary directory.
3. copy release/geoserver.nsi to temp/geoserver
4. copy release/dataDirPage.ini to temp/geoserver
5. copy release/splash.bmp to temp/geoserver
6. right click on the the geoserver.nsi file and select Compile NSIS Script.

Upon successful creation of the installer, the file geoserver-(version).exe will be created.

Step 14: Test Runnable Artifacts

It is always a good idea to test the newly-built artifacts. This can include:

1. Running the installer and trying it out some of the demo scripts
2. Unarchiving the binary distribution and trying out some of the demo scripts
3. Deploying the war file in a servlet container and trying out some of the demo scripts

Step 15: Upload to SourceForge

The next step is to upload the files to SourceForge. They have great docs on how to perform the release. You will need release tech permissions to perform the release. The GeoServer project page is at http://geoserver.sourceforge.net.  For more information on the file release system, go to: SourceForge File Release System

Make sure you upload the plugins to the GeoServer Extensions project!

Step 16: Update the Website

1. Log in to the wiki at http://geoserver.org.
2. Create a new page, select Download as the page template, and fill in the GeoServer release number and SourceForge release ID.
3. Once the page is created and the links in it are updated to point to the Sourceforge download page, edit either the Latest or Stable page (depending on what type of release this is) to include your newly-created page.

Step 17: Move Open JIRA Issues

1. Log in to JIRA at http://jira.codehaus.org/browse/GEOS .
2. Select the current release version.
3. If there are open issues, select Bulk Change and move them to be "fixed for" the next version.  If no new version exists, you may have to create it (Manage Versions will allow you to do this).
4. When the release has no more open issues, go to Manage Versions and select Release on the version to be released.  Follow the instructions.

Step 18: Upload to Codehaus Maven Repository

If this is a stable release (not a beta or an RC) the next step is to update the GeoServer jars in the Codehaus Maven Repository. This is done to allow other projects that depend on GeoServer through maven dependencies to be updated. Instructions.

Step 19: Announce the Release

The final step is announcing to the world that you just put out a release. The first place is the GeoServer blog at http://blog.geoserver.org.  The announcement should be a few paragraphs long, the first paragraph should give the basic information and direct links to the download. The following paragraphs should give more information and often a good story. Then email the geoserver-devel list, as many people are pretty much only on the list for release announcements. Next we generally update the freshmeat entry, as it gets quite a few hits as the release will appear on the front page. The story can also be added as a story on sourceforge, as sometimes those will get picked up and placed on the main sourceforge page. Variations or cut and paste from the homepage story work just fine. Any other places to announce it are fair game.