HomeDownloadsUser GuideDevelopment

Development: Release

This document gives step by step instructions on how to create a binary release and deploy it to our project page at https://forge.osor.eu/projects/openpermis/ .

Note!

The information provided on this page is only relevant for committers of this project.
You will need to have a Releaser role on the OSOR.eu forge to deploy a release of OpenPERMIS.

Overview

Preparations
1. Prerequisites Make sure everything is ok before starting the release process.
2. Build Information Update the log of changes and the versioning files.
3. Since Tags Update @since source code Javadoc tags
4. Checkin Commit the build information and since tags.
Building
5. Tagging Create a tag for the release to build.
6. Exporting Check out (export) the tagged release sources.
7. Building Building the complete release packages.
Deployment
8. Packages Deploying the release packages.
9. Website Uploading the documentation to the website.

Preparations

Before we can create and deploy a new release we have to make sure that the package is in a state that can be deployed...

1. Prerequisites

To build a new release make sure the following preconditions are met:

  1. build world runs through and doesn't report any errors.
  2. The auditing information looks acceptable.

2. Updating Build Information

The build information consists of a log of changes and versioning files that are included in the release modules (version.properties on the toplevel of the archives).

To update the changelog and versioning information there is a graphical tool that you can launch from the build system using:

On Unix / Mac OS X:

sh build.sh version

or on Windows:

build version

ChangeLog Editor

To build the release create a new version entry for module openpermis (as of release 0.3.0 we are only using one module version entry). Next choose the appropriate type (alpha/beta/stable) and enter the desired version number. The build number should automatically update to the last build number plus one - this number simply gets incremented whenever we make a new release so it serves as a single unique number that represents a build. In the changelog add a list of important changes you want to include in the homepage and the RSS feed.

When done hit the save button and exit the editor. The editor will update all versioning files required. Since we are only using one version module only the following files will be updated:

/shared/src/version.properties
The actual version file - bundled with all modules.
/shared/src/doc/changelog.xml
Complete log of changes in XML format.

3. Since Tags

To track versioning information in the API we use the custom tag @new. Whenever a new release is built and published these tags have to be replaced by the current release number so that users of the API are aware when a feature was introduced or changed.

Fortunately the build system automates this task once you have updated the build information correctly (see step 2 above). To convert @new to appropriate @since tags simply execute the following build command:

On Unix / Mac OS X:

sh build.sh since

or on Windows:

build since

4. Checkin

Once everything looks fine and the new release builds without any problems checkin all changes so that the HEAD revision corresponds to the version you want to release.

Make sure you run a build check to make sure the checkin version is sound.

Example for Unix / Mac OS X:

sh build.sh check
svn ci -m "Prepared release x.y.z."

Building

Now that we have a package which is ready for release we have to tag the repository so that we can later on identify the release and build the distribution package from the tagged version.

5. Tagging

To tag the current HEAD revision use the following command:

svn copy -m "Tagging the x.y.z release of the 'openpermis' project." \
         https://svn.forge.osor.eu/svn/openpermis/trunk/openpermis \ 
         https://svn.forge.osor.eu/svn/openpermis/tags/openpermis/release-x.y.z

Use the following naming scheme for release tags: release-x.y.z (where x.y.z denote the major, minor and revision number). Please note that the build number included in the versioning information is not part of the tag.

6. Exporting

To make sure we are building the distribution package exactly from the tagged version we have just created it is best to export the tagged version into a temporary directory and build the distribution there. This will also ensure (as a last chance to detect any errors) that the build runs through and all files required are checked in.

Example for Unix / Mac OS X:

mkdir /tmp/openpermis-release-x.y.z
cd /tmp/openpermis-release-x.y.z
svn export https://svn.forge.osor.eu/svn/openpermis/tags/openpermis/release-x.y.z

Use "release" as "user" when executing build setup. This will ensure that all releases are executed with the same user settings and that no modules or any auditing information is excluded. Use your usual site to configure the JVM used.

7. Building

Once you have successfully exported the release version for which to build the package simply setup the build system and perform a distribution build.

Example for Unix / Mac OS X:

cd /tmp/openpermis-release-x.y.z
sh build.sh setup release <site>
sh build.sh dist

Use "release" as "user" when executing build setup. This will ensure that all releases are executed with the same user settings and that no modules or any auditing information is excluded. Use your usual site to configure the JVM used.

Once the build completes the distribution archives can be found in your target folder:

/target/openpermis-x.y.z-bin.zip
The binary version of the release package.
/target/openpermis-x.y.z-complete.zip
The developer version of the release package that includes sources and Javadoc.

Deployment

Now that we got the two distribution archives we simply need to make them available on the OSOR.eu forge page and update the website with the latest release documentation.

8. Packages

Information will be added as soon as the first package has been deployed.

9. Website

Information will be added as soon as the first package has been deployed.