Title: LDAP Java API - Developer Guide Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # Developer Guide This guide is intened to be read by those who participate into the development of the LDAP API. Users of the API are expected to read the [User guide](user-guide.html). ## Getting the source, Building the trunks To get the source, build the *trunks/api* and get along with Maven. ## Versioning Scheme The version number of **LDAP API** 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 LDAP API 1.0 are described in [Coding Standards](coding-standards.html) 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 the LDAP API **Note: The release guide needs to be updated after git migration!** Here is a guide on how to cut a new release. This is a long process, expect it to last a couple of 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: :::text apache.snapshots.https username ******** apache.directory username /Users/username/.ssh/id_rsa 664 775 apache.releases.https username ******** stagingSite elecharny 664 775 apache-public apache.public https://repository.apache.org/content/groups/public/ apache-release ******** elecharny@apache.org 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: :::text gpg --gen-key gpg --fingerprint gpg --keyserver subkeys.pgp.net --send-keys
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
## Release process Since we are using Nexus for releases the release process is as follows (see also [Publishing maven artifacts](http://www.apache.org/dev/publishing-maven-artifacts.html#staging-maven)). ### Test the Project :::text $ mvn release:prepare -DdryRun=true Be aware that this phase will ask you about the next version, and most important, for the next SCM tag : :::text ... [INFO] Checking dependencies and plugins for snapshots ... What is the release version for "Apache Directory LDAP API"? (org.apache.directory.api:api-parent) 1.0.0-M16: : What is the release version for "Apache Directory LDAP API I18n"? (org.apache.directory.api:api-i18n) 1.0.0-M16: : What is the release version for "Apache Directory LDAP API Utilities"? (org.apache.directory.api:api-util) 1.0.0-M16: : ... What is SCM release tag or label for "Apache Directory LDAP API"? (org.apache.directory.api:api-parent) 1.0.0-M16: : ... ### Deploy a Snapshot :::text $ mvn deploy This is useful to verify your settings in ~/.m2/settings.xml (Nexus password and GPG key) ### Prepare the Release :::text $ mvn release:clean $ mvn release:prepare This creates a tag [here](https://gitbox.apache.org/repos/asf?p=directory-ldap-api.git) ### Stage the Release :::text $ mvn release:perform This deploys the release to a staging repository. Go to [the nexus server](https://repository.apache.org/index.html#stagingRepositories) and close the staging repository. ### Build the Site In order to be able to generate the site, you will have to modify the target/checkout/pom.xml file, by adding a line to the javadoc configuration (in two places) : :::text $ vi target/checkout/pom.xml ... org.apache.maven.plugins maven-javadoc-plugin private true none <---- This line ... and :::text ... org.apache.maven.plugins maven-javadoc-plugin Apache LDAP API ${project.version} API Documentation Apache LDAP API ${project.version} API Documentation 512m 1g true none <---- This line too ... then run the maven site goal : :::text $ cd target/checkout $ mvn site This creates the site. ### Sign the packages Now, you have to sign the binary packages which are in target/checkout/distribution/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 The produced packages already have .asc signature that you will need to remove : :::text $ cd target/checkout/distribution/target $ rm *.asc $ ~/sign.sh PGP Key ID: PGP Key Password: -n Signing: ./apache-ldap-api-1.0.0-M25-bin.tar.gz ... - Generated './apache-ldap-api-1.0.0-M25-bin.tar.gz.md5' - Generated './apache-ldap-api-1.0.0-M25-bin.tar.gz.asc' -n Signing: ./apache-ldap-api-1.0.0-M25-bin.zip ... - Generated './apache-ldap-api-1.0.0-M25-bin.zip.md5' - Generated './apache-ldap-api-1.0.0-M25-bin.zip.asc' ... You are done with the signature. For the record, here is the script shell you can use to sign the packages. Name it sign.sh, and put it into your home directory (on a unix based computer) : #!/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 "*.asc" ')' -and -type f) ; do if [ -f "$FILE.asc" ]; then echo "Skipping: $FILE" continue fi echo -n "Signing: $FILE ... " # SHA-256 if [ ! -f "$FILE.sha256" ]; then gpg -v --default-key "$DEFAULT_KEY" --print-md SHA256 "$FILE" > "$FILE".sha256 echo " - Generated '$FILE.sha256'" else echo " - Skipped '$FILE.sha256' (file already existing)" fi # SHA-512 if [ ! -f "$FILE.sha512" ]; then gpg -v --default-key "$DEFAULT_KEY" --print-md SHA512 "$FILE" > "$FILE".sha512 echo " - Generated '$FILE.sha512'" else echo " - Skipped '$FILE.sha512' (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 ### Publish Source and Binary Distribution Packages The sources, binaries and their signatures, have to be pushed in a place where they can be downloaded by the other committers, in order to be checked while validating the release. As the ~/people.apache.org server is not anymore available for that purpose, we use the [distribution](https://dist.apache.org/repos/dist/dev/directory) space for that purpose. If you haven't checked out this space, do it now : :::text $ mkdir -p ~/apacheds/dist/dev/directory $ svn co https://dist.apache.org/repos/dist/dev/directory ~/apacheds/dist/dev/directory That will checkout the full project distributions. You may want to checkout only the part that you are going to generate, to avoid getting Gb of data : :::text $ mkdir -p ~/apacheds/dist/dev/directory/api $ svn co https://dist.apache.org/repos/dist/dev/directory/api ~/apacheds/dist/dev/directory/api Now, create a sub-directory for the version you have generated (here, for version 1.0.0-RC1) : :::text $ mkdir ~/apacheds/dist/dev/directory/api/1.0.0-RC1 and copy the packages and signature to this area : :::text $ cd distributions/target $ cp apache-ldap-api--* ~/apacheds/dist/dev/directory/api/1.0.0-RC1 Last, not least, commit your changes :::text $ svn add ~/apacheds/dist/dev/directory/api/1.0.0-RC1 $ svn ci ~/apacheds/dist/dev/directory/api/1.0.0-RC1 -m "Apache LDAP API 1.0.0-RC1 packages" ### Test the New Version in ApacheDS and Studio In apacheds/pom.xml change the property, build ApacheDS, go into apacheds/service, and run ./apachds.sh to start the server. In studio/pom.xml change the and properties, build Studio, and start Studio in applications/applications_/target/ApacheDirectoryStudio-/. Connect to the started **ApacheDS**. ### Stage the release Go to [https://repository.apache.org/index.html#stagingRepositories](https://repository.apache.org/index.html#stagingRepositories) and close the staging repository. ### Vote Start a 72h vote at the dev mailing list. ### Release If the vote succeeds LDAP API project can be released. Go to [https://repository.apache.org/index.html#stagingRepositories](https://repository.apache.org/index.html#stagingRepositories) and release the staging repository so all artifacts are published to Maven central. The sources, binaries and their signatures, have to be pushed in a place where they can be downloaded by users. We use the [distribution](https://dist.apache.org/repos/dist/release/directory) space for that purpose. Move the distribution packages (sources and binaries) to the dist SVN repository: https://dist.apache.org/repos/dist/release/directory/api/dist/$(version) If you haven't checked out this space, do it now : :::text $ mkdir -p ~/apacheds/dist/release/directory $ svn co https://dist.apache.org/repos/dist/release/directory ~/apacheds/dist/release/directory That will checkout the full project distributions. You may want to checkout only the part that you are going to generate, to avoid getting Gb of data : :::text $ mkdir -p ~/apacheds/dist/release/directory/api/dist $ svn co https://dist.apache.org/repos/dist/release/directory/api/dist ~/apacheds/dist/release/directory/api/dist Then move the packages from 'dev' to 'release' : :::text # cd dist/release/directory/api/dist # cp ~/apacheds/dist/dev/directory/api/ . # svn add # svn ci ... # 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 ust 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 production. :::text $ cd ~/apacheds $ svn co https://svn.apache.org/repos/infra/websites/staging/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 : :::text $ cd ~/apacheds/production/content/api/gen-docs $ mkdir $ svn add Then copy the generated docs : :::text $ cp -r ~/apacheds/trunks/api/target/checkout/target/site/apidocs ~/apacheds/production/content/api/gen-docs/ $ cp -r ~/apacheds/trunks/api/target/checkout/target/site/xref ~/apacheds/production/content/api/gen-docs/ $ You have to check in those directories : :::text $ svn add /* $ svn ci -m "Injected 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 :::text $ cd ~/apacheds/staging/content/ $ vi extpaths.txt Add the following line : :::text ... # API api/gen-docs/ ... then save and check in the file extpaths.txt We also have to update the .htaccess file : :::text $ cd ~/apacheds/staging/content/api/gen-docs $ vi .htaccess And update the two last lines to refer to the version you've just released : :::text RewriteRule ^latest$ / RewriteRule ^latest/(.*)$ /$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. There are a few places to modify : * /lib/path.pm : update the $version_api variable with the new version. * /content/index.mdtext : same here, update the section, which contains the version. * /content/api/news.mdtext : add the news on top of this page * /content/api/download-old-versions.mdtext : add a new line on top of the array, which refers to the latest version before the new one Commit the changes, and publish the web site, you are done ! ### 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 !