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.
To get the source, build the trunks/api and get along with Maven.
The version number of LDAP API has the following form:
This scheme has three number components:
and an optional label that indicates the maturity of a release:
The applicable coding standards for LDAP API 1.0 are described in Coding Standards
There are some more rules, as we are using Java 8 now :
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).
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.
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>
Since we are using Nexus for releases the release process is as follows (see also Publishing maven artifacts).
$ 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 :
... [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: : ...
$ mvn deploy
This is useful to verify your settings in ~/.m2/settings.xml (Nexus password and GPG key)
$ mvn release:clean $ mvn release:prepare
This creates a tag here
$ mvn release:perform
This deploys the release to a staging repository.
Go to the nexus server and close the staging repository.
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) :
$ vi target/checkout/pom.xml ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <show>private</show> <nohelp>true</nohelp> <doclint>none</doclint> <---- This line ...
and
... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <windowtitle>Apache LDAP API ${project.version} API Documentation</windowtitle> <doctitle>Apache LDAP API ${project.version} API Documentation</doctitle> <minmemory>512m</minmemory> <maxmemory>1g</maxmemory> <linksource>true</linksource> <doclint>none</doclint> <---- This line too ...
then run the maven site goal :
$ cd target/checkout $ mvn site
This creates the site.
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 :
$ cd target/checkout/distribution/target $ rm *.asc $ ~/sign.sh PGP Key ID: <You public key> PGP Key Password: <Your 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
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 space for that purpose.
If you haven't checked out this space, do it now :
$ 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 :
$ 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) :
$ mkdir ~/apacheds/dist/dev/directory/api/1.0.0-RC1
and copy the packages and signature to this area :
$ cd distributions/target $ cp apache-ldap-api-<version>-* ~/apacheds/dist/dev/directory/api/1.0.0-RC1
Last, not least, commit your changes
$ 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"
In apacheds/pom.xml change the <org.apache.directory.api.version> property, build ApacheDS, go into apacheds/service, and run ./apachds.sh to start the server.
In studio/pom.xml change the <org.apache.directory.api.version> and <org.apache.directory.api.validversion> properties, build Studio, and start Studio in applications/applications_/target/ApacheDirectoryStudio-/. Connect to the started ApacheDS.
Go to https://repository.apache.org/index.html#stagingRepositories and close the staging repository.
Start a 72h vote at the dev mailing list.
If the vote succeeds LDAP API 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.
The sources, binaries and their signatures, have to be pushed in a place where they can be downloaded by users. We use the distribution 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 :
$ 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 :
$ 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’ :
# cd dist/release/directory/api/dist # cp ~/apacheds/dist/dev/directory/api/<version> . # svn add <version> # svn ci <version> ... # exit $
The packages should now be available on http://www.us.apache.org/dist/directory/api/dist/
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?
First of all, you must checkout the two CMS store for the site : staging and production.
$ 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 :
$ cd ~/apacheds/production/content/api/gen-docs $ mkdir <version> $ svn add <version>
Then copy the generated docs :
$ cp -r ~/apacheds/trunks/api/target/checkout/target/site/apidocs ~/apacheds/production/content/api/gen-docs/<version> $ cp -r ~/apacheds/trunks/api/target/checkout/target/site/xref ~/apacheds/production/content/api/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 :
... # API api/gen-docs/<version> ...
then save and check in the file extpaths.txt
We also have to update the .htaccess file :
$ cd ~/apacheds/staging/content/api/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.
You can now update the site, add a news on the front page, and publish the site.
There are a few places to modify :
Commit the changes, and publish the web site, you are done !
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 !