Edit this page

Releasing a new version of Apache Directory Studio

Warning: Work in progress

This page is not complete yet.

This guide describes the tasks that need to be done to release a new version of Apache Directory Studio.

Prerequisites

  • Have all required developments finished for the new version release.
  • Have the associated JIRA version road map cleaned with only resolved and/or closed items.

Verify the code and plugins bundles are ready for release

First, you need to verify that the code and plugins bundles are ready for release.
By that we mean that:

  • each file has its Apache Software License 2.0 header (Java files, XML files, etc.) and,
  • all the META-INF folders of all the plugins that will be shipped has the correct LICENSE.TXT (ASL 2.0) and NOTICE.TXT files.

If a file or a plugin lacks one of these requirements, fix it first before going on the next step.

Update the Release Notes file and version number

The "Release Notes" file (/docs/Release Notes.txt) must be updated using the JIRA exported roadmap.

You also need to update the version number.
The version number must follow the Eclipse guideline for version numbering (X.Y.Z.qualifier) and is composed of four parts:

  • X for major
  • Y for minor
  • Z for service
  • qualifier

This version number must be changed in the main pom.xml and in the Manifest of the help plugins and features.

Verify the RCP Application and Update Site

Obviously, before releasing, Apache Directory Studio must be fully functional.

We recommend you to highly test the RCP Application, but the Updade Site too before releasing.
We have a lot of people installing Apache Directory Studio from the Update Site, so this needs to be highly tested too.

Testing the RCP Application

To test the RCP Application, you need to build a version of Apache Directory Studio and then run it.

First, test that each Feature is correctly installed in Apache Directory Studio.
To do so, open the "Product Configuration" dialog from the menu "Help -> Software Updates -> Manage Configuration".
Verify then that each feature is correctly installed.


If a feature is not correctly installed, update the features details to fix the issue.

Then, test the behavior of Apache Directory Studio while using its plugins.

Testing the Update Site

If you've built a version, a zip archive containing the update site has been generated.

To test if the Update Site is working, download a simple Eclipse distribution, run it and install the Apache Directory Studio Features from this Update Site we've just created.

Unzip the archived update site to location where it can be accessed using the HTTP protocol (running Apache HTTPd for example).

Then install Apache Directory Studio.Open the "Install/Update" dialog from the menu "Help -> Software Updates -> Find and Install"
Then, choose "Search for new features to install"
Click on the "New remote site" button and locate the Update Site on your hard drive
Give the Update Site a name and click "Ok".
Click "Finish" to launch the Apache Directory Studio Features installation.
An "Updates" dialog should appears.

Verify that all the Features are in the list. Select them all and click on "Next".
Accepts the license and click "Next".
Finally, click "Finish" to install.
If an error occurs, you will need to update site to fix the problem.
Eclipse should ask you to relaunch it. Do so, and then test the installed plugins within Eclipse to see if they work properly.

Generate packages

To generate the package, execute the following command from the root of your Apache Directory Studio source checkout:

ant release

This command take a long time (around 15 minutes) and will create a "packages" folder and you'll find in it the different packages for each OS/Architecture.

The linux packages (i386, PPC and AMD64) can be distributed as is, while the packages for Windows and Mac OS X need some extra work.

Building the Windows installer

Creating the Mac OS X Disk Image (DMG)

Untar the Mac OS X archive of Apache Directory Studio.
Mount the Apache Directory Studio Disk Image.
Using a terminal, copy the "Release Notes.txt" and "NOTICE.TXT" files in the DMG whith the following commands:

cp Release\ Notes.txt /Volumes/Apache\ Directory\ Studio/
cp NOTICE.txt /Volumes/Apache\ Directory\ Studio/

Drag and drop the Apache Directory Studio Application from the archive to the DMG overwriting the existing file.

Launch Disk Utility (/Applications/Utilities/Disk Utility.app) and create a new Disk Image from folder (File -> New -> Disk Image from folder...), selecting "Apache Directory Studio" as source.

Select the destination file and save.

Launching the vote

Each release at the Apache Software Foundation requires a vote. The vote need to be started sending a mail at dev@directory.apache.org
using a title like this:

[VOTE][Studio] Release of Apache Directory Studio X.Y.Z

and a body that can be inspired from this:

Hi Dev,

One week after the release of the 1.0.0 version, Apache Directory Studio 1.0.1 seems ready for release.

It's fixes a really major bug with SSL connections not working in the LDAP Browser and a few others.

Here's the complete changelog:

    Apache Directory Studio 1.0.1

    Bug
      * [DIRSTUDIO-162] - Delete old RDN on rename has no effect
      * [DIRSTUDIO-180] - Connection wizard and properties tabs are out of order
      * [DIRSTUDIO-183] - It's not possible to select a Connection in a New Search
      * [DIRSTUDIO-186] - When copying an entry it isn't displayed correctly in the browser tree
      * [DIRSTUDIO-190] - SSL connections are no longer working

    Improvement
      * [DIRSTUDIO-185] - Provide completion for all attribute types in the attribute wizard

    Task
      * [DIRSTUDIO-181] - Update the documentation of the Schema Editor Plugin
      * [DIRSTUDIO-188] - Move LDIF Editor help to its own help plugin


Version 1.0.1 has been tagged in SVN here : https://svn.apache.org/repos/asf/directory/studio/tags/1.0.1/
The packages are available for testing here : http://people.apache.org/~pamarcelot/packages_1.0.1/

Time to vote:
[ ] +1 Release Apache Directory Studio 1.0.1
[ ] +/-0 Abstain
[ ] -1 Do not release Apache Directory Studio 1.0.1

Thanks,

[Developer's name]

As you can see in the mail's body, we provide a url for testers to get the packages and test them, so the packages need to be uploaded somewhere (probably on your people.apache.org account).
We also provide a SVN Tag, so we're freezing the code of this release and developers can still commit modification to the commom trunk.

You can use the following command to create the tag:

svn copy https://svn.apache.org/repos/asf/directory/studio/trunk/ https://svn.apache.org/repos/asf/directory/studio/tags/X.Y.Z -m "Tagging version X.Y.Z"

Signing the packages

Before releasing the packages on Apache Mirrors system, the prepared packages need to be signed.

To sign the release packages, copy-paste the "sign.sh" shell script in the folder in which are the packages and execute the following command using a terminal:

sh sign.sh

You will be asked for the id of the key to use for signing and its password.

Signing generates two files for each package, an MD5 file and an ASC file. These files must be deployed with the packages on the Apache Mirrors system.

Deploying the packages

Uploading the packages

To deploy the packages you first need to upload them to your people.apache.org account using the terminal and the 'scp' command.
If the folder named "packages" contains the signed packages, the following command will upload them to your account at people.apache.org:

scp -r packages/ [username]@people.apache.org:

Deploying the RCP Application packages

The RCP Application packages must deployed under the following location:

/www/www.apache.org/dist/directory/studio/stable/[X.Y.Z]/

Deploying the Update Site

The update site packages must deployed under the following location:

/www/www.apache.org/dist/directory/studio/update/
Warning
Don't overwrite existing packages (with same id and version number).