Deployer un artefact sur repo1.maven.org

Vous avez peut-être eu l’obsession de voir « maven » en train de télécharger vos propres artefacts à partir de son repository central. Du moins vous vous êtes sûrement posé la question : mon projet est mavenisé, open source, sur une forge publique (github, googlecode, etc.) et il est destiné à être utilisé par le plus grand nombre ; pourquoi ne pas le publier sur le Maven Central Repository (http://repo1.maven.org) ?

Au lieu de penser à ouvrir votre Nexus sur Internet ou encore à créer votre propre repository sur Google Code ou autre, nous vous proposons de directement déployer sur le Maven Central Repository, ce qui, en plus de vous épargner l’installation d’un repository, facilitera l’utilisation de votre artefact.

Le but de ce billet est de décrire la marche à suivre pour la publication d’un artefact en passant par le repository de Sonatype. Ce dernier étant un repository approuvé pour tout projet OSS comme c’est le cas du repository Apache (pour les projets Apache) et celui du Codehaus (pour les projets Codehaus). Le fait de passer par Sonatype vous garantit d’une part, un processus de validation structurant qui impose un ensemble de points de contrôle (licence, copyright, traçabilité, etc.) augmentant ainsi la qualité des métadonnées, et d’autre part une synchronisation rapide avec le Maven Central Repository.

Il s’agit également de vous faire profiter de notre expérience sur le sujet avec le déploiement de quelques artefacts tels que mindmap-maven-plugin, xebia-management-extras, xebia-spring-security-extras et xebia-servlet-extras.

Ce qui est présenté par la suite est basé principalement sur le guide officiel fourni par Sonatype: https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide

Choix de la licence du projet

Chacun appliquera sur son code la licence qui lui convient. C’est à la fois un choix « tactique » pour cibler ses utilisateurs et « philosophique » selon ses convictions. Pour résumer ce sujet qui mériterait un billet complet, il y a deux grandes familles de licences :

• les licences « business friendly » (Apache Software Licence, MIT, BSD, etc) qui facilitent l’intégration dans toute programme (y compris « close source » et commercial)
• les licences « business unfriendly » (GPL, Aferro GPL, etc) qui sont qualifiées de virales et ne permettent pas l’intégration dans des logiciels « close source »

Pour aller plus loin sur le sujet, nous vous recommandons 451 Chaos Group – 06/2011 : The trend towards permissive licensing et notre récent billet Réponses au Quizz Licences Open Source.

Application de la licence sur les fichiers de son projet

• Tous les fichiers doivent porter le header de la licence
• Un fichier LICENSE (exemple) à la racine doit être reporté dans les artefacts générés
• Un fichier NOTICE (exemple) à la racine doit mentionner les copyrights des dépendances

Si vous êtes dans le cas d’une licence APV2, vous pouvez toujours vous référer à ce lien : Applying the license to new software.

Le apache-rat-plugin permet de vérifier la conformité du projet et peut casser le build dans le cas contraire.

Exemple de déclaration des ressources dans un pom maven pour intégrer les fichiers LICENSE et NOTICE dans les artefacts:

<project ...>
 ...
 <resources>
  <resource>
   <directory>${basedir}/src/main/resources</directory>
   <filtering>true</filtering>
  </resource>
  <resource>
   <directory>${basedir}</directory>
   <targetPath>META-INF</targetPath>
   <includes>
    <include>LICENSE</include>
    <include>NOTICE</include>
   </includes>
  </resource>
 </resources>
 ...
</project>

Exemple d’utilisation du apache-rat-plugin dans un pom maven:

<project ...>
   ...
   <plugin>
    <groupId>org.apache.rat</groupId>
    <artifactId>apache-rat-plugin</artifactId>
    <version>0.7</version>
    <executions>
     <execution>
      <phase>verify</phase>
      <goals>
       <goal>check</goal>
      </goals>
     </execution>
    </executions>
   </plugin>
   ...
</project>

Mise en conformité du pom maven

Le fichier pom.xml doit obligatoirement porter les informations suivantes:

• <modelVersion>
• <groupId>
• <artifactId>
• <version>
• <packaging>
• <name>
• <description>
• <url>
• <licenses>
• <scm><url>
• <scm><connection>
• <developers>

Pour faciliter le déploiement des artifacts sur le repository http://oss.sonatype.org qui sert de bac à sable de validation, le plus simple est de référencer le pom parent « org.sonatype.oss:oss-parent » fourni par sonatype. Exemple :

<project...>
  <parent>
    <groupId>org.sonatype.oss</groupId>
    <artifactId>oss-parent</artifactId>
    <version>7</version>
  </parent>
  ...
</project>

(?) De plus, il est fortement recommandé que le pom.xml ne référence pas de repository (cf. Why Putting Repositories in your POMs is a Bad Idea)

Signature des artefacts avec GPG

Les artefacts publiés sur repo1.maven.org doivent être signés.

Le pom parent org.sonatype.oss:oss-parent utilise le maven-gpg-plugin qui se base sur l’implémentation GnuPG du standard OpenPGP pour la signature des artefacts. Pour s’appuyer dessus, vous devez :

• Installer un client GPG (e.g. Mac GNU Privacy Guard)
• Créer votre paire de clés GPG (privée/publique) (cf GPG Quick Start par Paul Heinlein)
• Distribuer votre clé publique sur un serveur de clé PGP:

gpg --keyserver hkp://pool.sks-keyservers.net --send-keys your_public_key_ID

• Tester votre clé avec maven-gpg-plugin:

mvn package gpg:sign -Dgpg.passphrase=PASSPHRASE

Création d’un compte sur oss.sonatype.org

La création d’un compte pour déployer sur oss.sonatype.org se fait en créant un compte https://issues.sonatype.org/ .

Création d’un ticket Jira de demande d’autorisation : obligatoire pour la première publication

Il vous faut faire une demande à Sonatype en créant un ticket Jira de demande de publication d’artefact dans lequel on précise :

• Summary : description rapide du projet
• GroupId : groupId du projet Maven. Ce groupe doit reprendre le nom de domaine du projet (e.g. : fr.xebia, com.googlecode.myproject, etc.)
• Project URL : l’url du projet (e.g. http://xebia-france.googlecode.com/
• SCM URL : l’url du gestionnaire de source (e.g. http://xebia-france.googlecode.com/svn/)
• Nexus Username : le ou les logins de connexion au JIRA : https://issues.sonatype.org/
• Already Sync To Central : indique si des versions de l’artefact ont déjà été déployées sur le Maven Central Repository (si oui, Sonatype les réintégrera dans le fichier maven-metadata.xml)
• Description : toute information complémentaire

Exemple de demande :  OSSRH-995 : Managements extras : jmx-ification of util.concurrent / dbcp / jms, @Profiled annotation, etc

Déploiement des snapshots et des staging releases avec maven

Compléter l’élément SCM avec les informations de votre repository

• Subversion:

<project>
  ...
  <scm>
    <connection>scm:svn:http://host_name/svn/path_to_project/trunk/</connection>
    <developerConnection>scm:svn:https://host_name/svn/path_to_project/trunk/</developerConnection>
    <url>http://host_name/svn/path_to_project/</url>
  </scm>
  ...
</project>

• Github:

<project>
  ...
  <scm>
    <connection>scm:git:git@github.com:user/project_name.git</connection>
    <developerConnection>scm:git:git@github.com:user/project_name.git</developerConnection>
    <url>git@github.com:user/project_name.git</url>
  </scm>
  ...
</project>

Configurer le fichier settings.xml

• Accès au repository nexus de sonatype:

<settings>
  ...
  <servers>
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your_jira_id</username>
      <password>your_jira_pwd</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your_jira_id</username>
      <password>your_jira_pwd</password>
    </server>
  </servers>
  ...
</settings>

• Accès au repository du code source

<settings>
  ...
  <servers>
    <server>
      <id>host_name_of_your_scm_url</id>
      <username>user_name</username>
      <password>password</password>
    </server>
  ...
</settings>

Préparer la release: Création d’un nouveau tag sur le repository du code source

mvn release:prepare -Dresume=false (alternativement mvn release:clean release:prepare)

Déployer le nouveau tag dans le staging repository

mvn release:perform -Darguments=-Dgpg.passphrase=<<PASSPHRASE>>

Publication de votre artefact : utilisation de nexus-maven-plugin

Ajouter org.sonatype.plugins dans la section <pluginGroups> du fichier settings.xml

<settings>
  ...
  <pluginGroups>
    <pluginGroup>org.sonatype.plugins</pluginGroup>
  </pluginGroups>
  ...
</settings>

Afficher la liste des staging repositories : un staging repository par artefact

mvn nexus:staging-list

Ce qui vous permettra d’obtenir la liste des repositories ouverts et clôturés si il en existe :

Clôturer un staging repository

mvn nexus:staging-close

Sélectionnez à partir de la liste le repository à clôturer et suivre les instructions:

Publier l’artefact : action irréversible (aucun update ou delete ne sera possible)

mvn nexus:staging-promote

Sélectionnez le repository à publier:

Vous pouvez maintenant retrouver votre actefact sur le releases repository de Sonatype en attendant la synchronisation avec le repo1.maven.org qui vous permettra après quelques heures de le voir à partir du Maven Central Repository Browser

Activer la synchronisation avec le repository central repo1.maven.org

Pour une première publication, vous avez besoin de compléter le ticket JIRA précédemment créé par un commentaire afin de communiquer à Sonatype que votre staging repository est passé en « released ». Après étude, Sonatype activera la synchronisation centrale et fermera votre ticket.

Désormais, vos futures publications seront synchronisées automatiquement (pas besoin de création de ticket JIRA pour les prochaines releases).

Et l’impact du clash entre Sonatype et la Fondation Apache dans tout ça ?

La Fondation Apache et la société Sonatype sont en grand froid en ce moment (Maven Dev Mailing List : PMC change explanation). Nous ne polémiquerons pas sur le sujet. Nous n’avons pas vu d’impact sur la publication d’artefacts sur la Maven Central Repository (maven.org est géré par Sonatype, et non par la Fondation Apache).