Publishing javassist releases to Sonatype public repo/maven central

This page describes the process for deploying a javassist project release from relase 3.13.0.GA onwards to the Sonatype public repository and from there to maven central. Althoguh it focusses on explaining how to upload javassist releases it should provide enough information to guide anyone wanting to upload some other project's artifacts to Sonatype/maven central

Why publish to Sonatype?

Previously javassist has published to the JBoss repo. The motive for moving deployment to the Sonatype repo is that it automatically synchronizes installed jars with maven central. Although javassist is a JBoss hosted project it is used by non-JBoss projects. So deploying to Sonatype/maven central gives two successive advantages:

  • Projects which have no dependency on JBoss can depend on javassist without needing to reference the JBoss repo. As a consequence their dependent projects no longer need to reference the JBoss repo and so on  i.e. this removes the need to introduce the JBoss repo into any upstream dependency chain.
  • As a direct consequence projects which depend on javassist can install their jars to the maven repo. maven central will only host artifacts whose dependencies are also located in the central repo i.e. it will not allow other repos to be introduced via the downstream dependency chain.

pom Conformance Requirements

Sonatype and maven central are fussy about what they expect to find in their poms. The javassist pom has been modified to meet these pom conformance requirements.

Locating Old and New javassist Releases

As of release.3.13.0.GA the javassist project is now set up to publish releases to the Sonatype public repo. Sonatype will ensure that these new releases are automatically synced with the maven central repo. The JBoss repo will automatically inherit these new releases form maven central making them available for use in JBoss projects.

 

In order to conform to Sonatype and Maven Cetral guidelines all releases from 3.13.0.GA onwards are installed using groupid org.javassist. Older releases are currently located  in the JBoss public repo under the old groupid javassist. These oleder releases are in the process of being  migrated to the maven central repo under the old groupid. However, they are currently still available at the JBoss repo.

 

Snapshot releases are still only deployed to the JBoss snapshots repo. At some point this may be changed so that they are deployed to  the sonatype public snapshots repo but this change should not be critical for most dependent projects.

 

Deploying a javassist tags Release

Deployment of a release from the svn tags tree requires first checking out the tag

$ svn co https://svn.jboss.org/repos/javassist/tags/rel_X_Y_Z_GA

$ cd rel_X_Y_Z_GA

n.b. ensure that the version tags defined in pom.xml and build.xml match those used to create the svn tags directory

pom.xml
  . . .
  <groupId>org.javassist</groupId>
  <artifactId>javassist</artifactId>
  <version>X.Y.Z-GA</version>
  . . .

 

build.xml

  . . .

<property name="dist-version" value="javassist-X.Y.Z-GA"/>

Anyone with appropriate upload permission can deploy directly to the JBoss repo.

$ mvn javadoc:jar deploy

This will install a  class jar, a source jar and a javadoc jar in the JBoss staging repo. You can then follow the usual process for closing, validating and then promoting the jars to the public repo. However, this step is unnecessary since upload to Sonatype/maven central will make the jars available via the JBoss releases repo.

 

Uploading to the Sonatype repo requires some preliminary steps described below. Once these have been performed it is almost as simple as uplaoding to the JBoss repo:

$ mvn  -P centralRelease javadoc:jar deploy

 

This should install a gpg-signed class jar, source jar and javadoc jar in the Sonatype staging repo. You use the same process for closing, validating and then promoting the jars to the public repo as applies with the JBoss staging repo.

Warning

There is a bug in maven 2.2.0 and earlier which causes it to generate an incorrect checksum for the uploaded jars. Be sure to upload using maven version 2.2.1 or higher (e.g. 3.0.beta1)

Preliminaries Steps for Sonatype Upload

There are several preliminary steps which must be performed before you can upload to the Sonatype repo.

Add a Developer Entry

The pom shoud be updated to include your details as a javassist developer in the developers section. Ideally this should be done before a release has been tagged.

 

  <developers>
    . . .

  <developer>
      <id>adinn</id>
      <name>Andrew Dinn</name>
      <email>adinn@redhat.com</email>
      <organization>JBoss</organization>
      <organizationUrl>http://www.jboss.org/</organizationUrl>
      <roles>
        <role>contributing developer</role>
      </roles>
      <timezone>0</timezone>
    </developer>
    . . .

Acquire Sonatype JIRA Login

You need to obtain a login for the Sonatype JIRA system. This allows you to raise a JIRA to negotiate access to the repo. It is also used as your login when uplaoding to the repo.

 

  • Go to the front page of the Sonatype JIRA system and click where it says sign up for an account under the box asking for a user name
  • Raise a JIRA asking to be added to the list of org.javassist developers with upload capability (here is the original JIRA which requested permission to uplaod the project)

 

Obtain and Export a gpg Public Key

The Sonatype repo requires all jars to be signed so you need to obtain a signing key and export it to a public key server in order for the signed jars to be verified. If you already have a gpg key then you only need to perform the export step.

  • Create a gpg key

$ gpg2 ---gen-key

gpg (GnuPG) 1.4.10; Copyright (C) 2008 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection?
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)
Key does not expire at all
Is this correct? (y/N) y

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: Fred Bloggs
Email address: fred.bloggs@jboss.org
Comment: Javassist Developer
You selected this USER-ID:
    "Fred Bloggs (Javassist Developer) <fred.bloggs@jboss.org>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.


Passphrase: ***********

Repeat Passphrase: ***********

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
..+++++
...+++++
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
....+++++
...+++++
gpg: key 9E0FB9ED marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
pub   2048R/9E0FB9ED 2010-07-27
      Key fingerprint = C469 AD5F EF38 FC57 5230  02CF 9C0C 9DE4 9E0F B9ED
uid                  Fred Bloggs (Javassist Developer) <fred.bloggs@jboss.org>
sub   2048R/690CD282 2010-07-27

 

Note that you are prompted  to insert a passphrase which you will also be required to enter when you use the key to sign the jars. The private and public keys are stored in dorectory ${HOME}/.gnupg. You can list your keys using command gpg2 --list-keys.

 

  • Make your public key available on key server hkp://pgp.mit.edu/

$ gpg2 --keyserv hkp://pgp.mit.edu/ --send-keys 9E0FB9ED

You can now use your saved key and the passphrase you supplied when you created  them to upload to Sonatype. However, you might also want to insatll the passphrase in your settings.xml file so you don't have to keep typing it in every time  a jar is encrypted.

 

Configure Your gpg Passphrase in settings.xml

Release jars need to be signed in order to upload them to the Sonatype repo so you will be asked 3 times for your passphrase unless you configure the maven build with the necessary information. The sonatype profile (-P centralRelease) in the project pom adds the gpg plugin to the build. This plugin is configured so that you can pass it a gpg passphrase by setting the required  property in ${HOME}/.m2/settings.xml. Obviously you only need to do this when uploading to Sonatype so it makes sense to place the property in a profile entry labelled with id centralRelease

 

<profiles>
  . . .
  <profile>
    <id>centralRelease</id>
    <properties>
      <gpg.passphrase>foobar</gpg.passphrase>
    </properties>
  </profile>
  . . .