Versioning Scheme

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

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

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:

<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: