Developers Guide

Getting the source, Building the trunks

To get the source, build the trunks and get along with Maven, follow the instruction given in this page: AUG : 0.2. Building trunks

Versioning Scheme

The version number of ApacheDS has the following form:

<major>.<minor>.<micro> \[-M<milestone number> or -RC<release candidate number>]

This scheme has three number components:

  • The major number increases when there are incompatible changes in the API.
  • The minor number increases when a new feature is introduced.
  • The micro number increases when a bug or a trivial change is made.

and an optional label that indicates the maturity of a release:

  • M (Milestone) means the feature set can change at any time in the next milestone releases. The last milestone release becomes the first release candidate after a vote.
  • RC (Release Candidate) means the feature set is frozen and the next RC releases will focus on fixing problems unless there is a serious flaw in design. The last release candidate becomes the first GA release after a vote.
  • No label implies GA (General Availability), which means the release is stable enough and therefore ready for production environment.
A stable version is a version with a frozen set of features, and a frozen API. We don't release a version if all the integration tests are not passing, so any release should be considered stable enogh to be used.
Although we may add new features between two milestones, and the data structure may change, which may imply that the data have to be extracted and reimported in order for the server to be operational.
The configuration might also evolve between two versions.

Coding standards

The applicable coding standards for ADS 2.0 are described in Coding Standards

There are some more rules, as we are using Java 6 now :

  • Use generics as much as you can. Generic are a good way to avoid casting, and it enforce the usage of the correct type.
  • If you can avoid Iterators, do so. There is this cool construction with a for( Type t: ) : use it !
  • Use assert. It's usefull, especially instead of a bunch of if () then throw Exception* when controlling incoming parameters
  • Use the new Enum type !

Releasing ApacheDS

Here is a guide on how to cut a new release. This is a long process, expect it to last a few hours !

First, you need to have a recent version of Maven (we are using 3.0.4) and a recent version of the JDK (1.7 is ok, it should also build with 1.6).

Maven Settings

You'll need a settings section for the Nexus and people.apache.org servers with a password or a path to the SSH key used. Here's what my settings.xml file in ~/.m2 looks like:

<settings>

  <servers>
    <!-- To publish a snapshot of some part of Maven -->
    <server>
      <id>apache.snapshots.https</id>
      <username>username</username>
      <password>********</password>
    </server>

    <!-- To publish a website using Maven -->
    <server>
      <id>apache.directory</id>
      <username>username</username>
      <privateKey>/Users/username/.ssh/id_rsa</privateKey>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>

    <!-- To stage a release of some part of Maven -->
    <server>
      <id>apache.releases.https</id>
      <username>username</username>
      <password>********</password>
    </server>

    <!-- To stage a website of some part of Maven -->
    <server>
      <id>stagingSite</id> <!-- must match hard-coded repository identifier in site:stage-deploy -->
      <username>elecharny</username>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>

  </servers>

  <profiles>
    <profile>
      <id>apache-public</id>
      <pluginRepositories>
        <pluginRepository>
          <id>apache.public</id>
          <url>https://repository.apache.org/content/groups/public/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>

    <profile>
      <id>apache-release</id>
      <!-- Configuration for artifacts signature -->
      <properties>
        <gpg.passphrase>********</gpg.passphrase>
        <gpg.keyname>elecharny@apache.org</gpg.keyname>
      </properties>
    </profile>
  </profiles>

</settings>

Just replace your username, passwords and paths. Note that the username and password is your Apache LDAP account.

You'll need to provide the passphrase in the settings.xml to access the gpg secret key installed on your host. This is due to a bug with the passphrase prompt in the maven-gpg-plugin. So unfortunately we must provide the passphrase in the settings.xml file in clear text. This should change in the future when this bug is fixed. Note that this passphrase is put into the release profile which we activate to properly sign and release the artifacts and poms via the release plugin.

GPG Key

All subprojects are configured to deploy signatures for the artifacts uploaded to the repository. The gpg plugin will check use the default gpg key for the user deploying the project with the release:perform directive of the release plugin. This will prompt you for the passphrase for the default key. If you do not have one setup the build will fail.

You can generate and upload a PGP key to a PGP keyserver using the following commands:

gpg --gen-key
gpg --fingerprint
gpg --keyserver subkeys.pgp.net --send-keys <your key's id from last command>
Make sure to have created the .pgpkey in your p.a.o/~ directory and to have added your public key to the KEYS file. See also http://people.apache.org/~henkp/repo/faq.html#4

Releasing ApacheDS

Now that your environment has been setup, we will show you how to build and release the ApacheDS subproject. Keep an eye out for warnings and note sections that show version specific differences in this process.

Manual Steps

Some things have not yet been automated with maven and require users to manually edit some files. Below are the steps to follow.

Update the apacheds/pom.xml

The current apacheds/pom.xml contains references to LDAP API SNAPSHOTs, which is not good. You have to bump up those references to the latest LDAP-API version.

Update service/apacheds.sh and service/apacheds.bat

Edit the apacheds.sh/bat files in the service project directory to update the revision numbers used in that file to reference non-SNAPSHOT releases.

Release process

Since we are using Nexus for releases the release process is as follows (see also Publishing maven artifacts.

Test the Project
$ mvn release:prepare -DdryRun=true

Replace the version by the new version. Be careful, and remove the 'apacheds-parent-' which is proposed for the new tag. We should just use the version number.

Deploy a Snapshot
$ mvn deploy

This is useful to verify your settings in ~/.m2/settings.xml (Nexus password and GPG key)

Prepare the Release
$ mvn release:clean
$ mvn release:prepare

This creates a tag here

Stage the Release
$ mvn release:perform

This deploys the release to a staging repository. Go to Staging Repositories and close the staging repository.

Build the Site

In order to generate the site, you have to comment some modules in the apacheds pom.xml file :

<!--module>installers-maven-plugin</module-->
<!--module>installers</module-->

Then you can start the maven command :

$ cd target/checkout
$ mvn site

This creates the site and the Javadocs.

Now, you have to sign the sources packages which are in apacheds/target/checkout/target. Use your PGP key ID (the pub key, 4096R/[XXXXXXX] where [XXXXXXX] is the key ID)

You can get the keys by typing :

gpg --list-keys

You can use this small script that does the job (copy-paste this code in a file named sign.sh in your path) :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#!/bin/sh

echo "PGP Key ID: "
read DEFAULT_KEY

echo "PGP Key Password: "
stty -echo
read PASSWORD
stty echo
echo ""

for FILE in $(find . -maxdepth 1 -not '(' -name "sign.sh" -or -name ".*" -or -name "*.md5" -or -name "*.sha1" -or -name "*.asc" ')' -and -type f) ; do

    if [ -f "$FILE.asc" ]; then
        echo "Skipping: $FILE"
        continue
    fi

    echo -n "Signing: $FILE ... "

    # MD5
    if [ ! -f "$FILE.md5" ];
    then
        openssl md5 < "$FILE" | cut "-d " -f2 > "$FILE.md5"
        echo "  - Generated '$FILE.md5'"
    else
        echo "  - Skipped '$FILE.md5' (file already existing)"
    fi

    # SHA1
    if [ ! -f "$FILE.sha1" ];
    then
        gpg -v --default-key "$DEFAULT_KEY" --print-md SHA1 "$FILE" > "$FILE".sha1
        echo "  - Generated '$FILE.sha1'"
    else
        echo "  - Skipped '$FILE.sha1' (file already existing)"
    fi

    # ASC
    if [ ! -f "$FILE.asc" ];
    then
        echo "$PASSWORD" | gpg --default-key "$DEFAULT_KEY" --detach-sign --armor --no-tty --yes --passphrase-fd 0 "$FILE"
        echo "  - Generated '$FILE.asc'"
    else
        echo "  - Skipped '$FILE.asc' (file already existing)"
    fi
done

Then to sign the packages :

$ sign.sh
PGP Key ID: 
<your PGP key>
PGP Key Password: 
<Your password>

-n Signing: ./apacheds-parent-<version>-source-release.zip ... 
- Generated './apacheds-parent-<version>-source-release.zip.md5'
- Generated './apacheds-parent-<version>-source-release.zip.sha1'
- Generated './apacheds-parent-<version>-source-release.zip.asc'
$
Publish Source Distribution Package
$ cd target/checkout/target
$ scp apacheds-parent-<version>-source-release.zip* people.apache.org:public_html/apacheds-<version>
Test the new version

The best way to do that is to download the sources, extract them, build the server and the installers, and check if the installers are correctly working. Then check that the server is correctly running.

Create the installers

We now have to create the installers. Go into the target/checkout directory and run :

$ cd apacheds/target/checkout/installers
$ mvn clean install -Pinstallers

This will create the installers in the target/checkout/installers/target/installers directory

Sign those installers using the sign.sh script, and copy them in people.apache.org/public_html/apacheds-

$ cd apacheds/target/checkout/target/installers/target/installers
$ scp apacheds-<version>* people.apache.org:public_html/apacheds-<version>

Note : you will need a Debian, a Fedora and a Windows server to generate dedicated binaries for those platforms, or you can use rpmbuild, dpkg or nsis if you don't want to use many different servers.

Update your index.html file on people.apache.org/public_html to make the packages visible. Here is an example of possible content :

<h2>Last Directory Server <version> sources tarballs</h2>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-parent-<version>-source-release.zip">apacheds-parent-<version>-source-release.zip</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-parent-<version>-source-release.zip.asc">apacheds-parent-<version>-source-release.zip.asc</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-parent-<version>-source-release.zip.md5">apacheds-parent-<version>-source-release.zip.md5</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-parent-<version>-source-release.zip.sha1">apacheds-parent-<version>-source-release.zip.sha1</a><br>

<h2>Last Directory Server <version> installers</h2>
    <h3>Plain 32 bits binary installers</h3>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-32bit.bin">apacheds-<version>-32bit.bin</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-32bit.bin.asc">apacheds-<version>-32bit.bin.asc</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-32bit.bin.md5">apacheds-<version>-32bit.bin.md5</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-32bit.bin.sha1">apacheds-<version>-32bit.bin.sha1</a><br/>
    <br/>
    <h3>Plain 64 bits installers</h3>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-64bit.bin">apacheds-<version>-64bit.bin</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-64bit.bin.asc">apacheds-<version>-64bit.bin.asc</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-64bit.bin.md5">apacheds-<version>-64bit.bin.md5</a><br/>
    <img src="/icons/compressed.gif" alt="[   ]"><a href="apacheds-<version>/apacheds-<version>-64bit.bin.sha1">apacheds-<version>-64bit.bin.sha1</a><br/>
    <br/>
...
Vote

Start a 72h vote at the dev mailing list.

Release

If the vote succeeds Apacheds project can be released.

Go to https://repository.apache.org/index.html#stagingRepositories and release the staging repository so all artifacts are published to Maven central.

Move the distribution packages (sources and binaries) to the dist SVN repository: https://dist.apache.org/repos/dist/release/directory/apacheds/dist/$(version)

The best solution would be to checkout the directory in people.apache.org, to copy the packages in the right place, and to check in the changes :

$ ssh people.apache.org
# svn co https://dist.apache.org/repos/dist/release/directory/apacheds/dist/ apacheds-dist
# cd apacheds-dist
# mkdir <version>
# cp ../public_html/apacheds-<version>/* <version>
# svn ci <version>
...
# exit
$

The packages should now be available on http://www.us.apache.org/dist/directory/api/dist/

Deploy the Javadocs and XRef

We now can deploy the generated Javadoc and cross-reference pages. They are generated in the following directory :

target/checkout/target/site

We will copy two directories :

apidocs
xref

Staging or Production?

Those files will be stored on the production server only !!! And some extra caution must be taken not to delete them when we will publish the staging site too...

First of all, you must checkout the two CMS store for the site : staging and revision.

$ cd ~/apacheds
$ svn co https://svn.apache.org/repos/infra/websites/production/directory/trunk staging
...
$ svn co https://svn.apache.org/repos/infra/websites/production/directory production
...

Now, you will first add the directory for the newly generated version :

$ cd ~/apacheds/production/content/apacheds/gen-docs
$ mkdir <version>

Then copy the generated docs :

$ cp -r ~/apacheds/trunks/apacheds/target/checkout/target/site/apidocs ~/apacheds/production/content/apacheds/gen-docs/<version>
$ cp -r ~/apacheds/trunks/apacheds/target/checkout/target/site/xref ~/apacheds/production/content/apacheds/gen-docs/<version>
$

You have to check in those directories :

$ svn add <version>
$ svn ci <version> -m "Injected <version> javadocs"

Now, you have to update the staging site :

extpaths.txt

This file list the file on the production site that will not be overriden by the publication of the staging site. It has to be updated

$ cd ~/apacheds/staging/content/
$ vi extpaths.txt

Add the following line :

...
# Apacheds
apacheds/gen-docs/<version>
...

then save and check in the file .htaccess

We also have to update this file :

$ cd ~/apacheds/staging/content/apacheds/gen-docs
$ vi .htaccess

And update the two last lines to refer to the version you've just released :

RewriteRule ^latest$ <version>/
RewriteRule ^latest/(.*)$ <version>/$1

Save and commit the file.

Update the web site

You can now update the site, add a news on the front page, and publish the site.

Inform the world !

After 24h, you can now inform the world about the release.

Send a mail to the users and dev mailing list, and one to the announce@apache.org

You are done !